permittable 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0af0930f23dca74dd690373044ec7ee08ae68a2562a34db3b55c4dff2879c82e
-  data.tar.gz: d838905e4413a8d0abd3aaed67a6b43caedf32c9387802db0f761da11c1d9ab5
+  metadata.gz: e135a1605d2d98e7c3a3952e2f9dc47394a656249f52d22b7018ed5dc15b23cb
+  data.tar.gz: f3748c6014a1f74099719fc8c42af289910c9f94d36687837cbe409fd67538a1
 SHA512:
-  metadata.gz: 5f4e6649f02667d1a2ea035974ec110c47b0e5ed1d8337776a97f51753e6c67a27c6da2d72516834d780bab1481ec6356c8ea20a29b39059df85296bdda42516
-  data.tar.gz: e2837022cae64c9e74e6c83e6dc48627535d782d91eab9546887f2d2ecf99cb8083869135ec2011dde222eaaaa0f1a36c893bf382f3c7b549c66d0d72a76d4d7
+  metadata.gz: 12881e40e20e390c7eb93963a5ca89aa402ed58d79eb0bfa7383d7a2ea6c5b93f6d61d1b35c94ed27b3b75774ddc75256e1d176f9cea5470d06200f64aaecb7e
+  data.tar.gz: 312bd2b824147af2821dc318c0a66a250d65bd7626d80574e91a0bfb5cc06159a0e22428e30b6d463bfe57ece1fe72c56b4ca8b513b7cdbde1419eb637cd0533

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 <!-- CHANGELOG.md -->
 
+## 0.10.0 (2026-09-30)
+<!-- title: canonical numeric strings, the app's own CSRF param, and defaults that agree with requests -->
+
+Ten fixes and no new surface. Three change what an existing contract does. A numeric string must now be spelled canonically: `Integer()`, `Float()` and `BigDecimal()` all read underscore separators and surrounding whitespace, so `"1_8"` was eighteen and `" 99 "` was ninety-nine, and both are now `invalid_type`. An array `default:` now runs its sub-fields' `transform:` when the contract loads, so a request that omits the field and one that sends the default's value hand the action the same thing. And an app that renamed its CSRF parameter with `config.action_controller.request_forgery_protection_token` stops failing every form POST under `unknown: :error`. Alongside them: a `sensitive:` field no longer publishes its own `default:`/`example:` in the exported schema, a `message:` shared through `use` can no longer be rewritten from one contract into another, `permittable:generate` stops drafting an enum accessor the model does not answer to and stops hiding a real error behind an empty draft, and three pieces of process-wide state — the error-response schemas, the scalar JSON Schema entries and the `sensitive:` sink list — can no longer be corrupted by a caller or a concurrent class load.
+
+Minor rather than patch: the API is untouched, but two fixes are visible from outside. A client that pads a number with whitespace or underscores now gets a 422 where it used to get the number, and an array `default:` whose sub-fields declare `transform:` is now handed out transformed — that `transform:` is app code, and it now runs when the contract loads. Read the first and third entries under **Fixed** before upgrading if either applies to your contracts.
+
+### Fixed
+- **`:integer`, `:float` and `:decimal` read `"1_8"` as eighteen and `" 99 "` as ninety-nine.** The casts delegate to `Integer()`, `Float()` and `BigDecimal()`, which all accept underscore digit separators and surrounding whitespace — a convenience for a number literal in Ruby source, not for a request body, and the same kind of leniency the NaN/Infinity and underflow checks already close off through other doors. A numeric string is now checked against a canonical form before anything parses it: an optional sign, digits, an optional fraction and an optional exponent — `"-12"`, `"007"`, `".5"`, `"1.5e10"`, and `"1e400"` for `:decimal` all still cast — and anything else is `invalid_type`. `normalize:` is a `:string`-only option, so there is no in-contract way to keep the old whitespace tolerance; a client that pads a number has a formatting bug upstream, which is now reported rather than repaired.
+- **A CSRF parameter renamed with `request_forgery_protection_token` failed every form POST under `unknown: :error`.** The top-level exemption hard-coded Rails' default `authenticity_token`, so an app that renamed it got `{ param: "csrf_token", code: "unknown" }` on every ordinary form submission — exactly the failure the exemption exists to prevent, spelled with the app's own key. The controller's configured token name is now read fresh on each request (it can vary per controller, and Rails may not have finished initializing when the gem loads) and exempted alongside the fixed keys. A plain params duck and a standalone `Contract` have no such setting and are unchanged, and so is monitor mode's raw pass-through.
+- **An array `default:` skipped its sub-fields' `transform:`, so an omitted field and an explicitly-sent identical value diverged.** An authored array default is walked by the same code a request goes through, but that walk suppressed `transform:` on *every* field it visited rather than only the array's own. With `array :line_items, default: [{ "price" => "10.00" }] do optional :price, :decimal, transform: ->(v) { v * 100 } end`, a request omitting `line_items` got `price: 10` and one sending `[{ "price" => "10.00" }]` got `price: 1000`, and the exported OpenAPI `default` documented a value the server never produced. A sub-field's own `transform:` now runs over the default when the contract loads, so the stored value is what an equivalent request yields. The array field's **own** `transform:` still never runs over its default, exactly as `default:` documents, and the `with_default` matcher reads its expected array through the same walk, so it stays in agreement.
+- **A field's `message:` was never deep-frozen, so two contracts sharing it through `use` could corrupt each other.** `default:`, `example:` and `in:` are deep-copied and deep-frozen on declaration; `message:` was frozen only at the top level in its Hash form and not at all as a String. `Permittable.fields` splices a group's field hashes into each contract by reference, so `msg << " NOW"` on one contract's violation message rewrote the message every other contract using that group would render, for the life of the process. Both forms now go through the same copy-then-freeze as the other authored values.
+- **A `sensitive:` field's `default:`/`example:` were exported in the clear.** The field was marked `writeOnly` and registered for log redaction, and then the exported JSON Schema and OpenAPI document — the one output meant to leave the app, for client generators or a public docs endpoint — carried the real value under `default` and `examples`. Both keys are now omitted for a sensitive field, a child inheriting the cascade included; `description` is still exported, being authored prose rather than the value.
+- **`permittable:generate` drafted `Model.statuses.keys` for an accessor the model does not have.** The generator only checked that the pluralised enum name was a valid identifier, so a renamed or excluded accessor produced a draft that raised `NoMethodError` the moment it loaded — while the schema-drift guard's own error messages already made the safer choice. The draft now also checks `respond_to?` and otherwise spells the list as `Model.defined_enums["status"].keys`, which is always callable.
+- **`permittable:generate` swallowed every error while reading a model's columns and drafted an empty contract instead.** The rescue was a blanket `StandardError`, so a broken custom type adapter, or any plain bug, quietly produced a degraded draft with nothing to say why. It is now scoped to `ActiveRecord::ActiveRecordError`, the same rule `ColumnGuard.schema_reachable?` follows: a genuinely unreachable schema (no database yet, table not migrated) still degrades to "no columns", and anything else propagates.
+- **`OpenAPI.document` handed out its error-response schemas by reference, so a caller editing its own document rewrote them for every document generated afterward.** `ERROR_SCHEMA` and `PROBLEM_SCHEMA` are frozen, but Ruby's `freeze` is shallow: assigning into a nested level of a generated document raised nothing and permanently changed the constant. Each document now gets a deep copy. The JSON Schema exporter had the same shape of exposure — a `SCALAR_SCHEMAS` entry was shallow-copied, so every `:decimal` schema shared one live `type` Array with the constant — and now deep-copies too. Nothing inside the gem mutated either in place; this closes the door on a caller doing so.
+- **`sensitive:` sink callbacks were iterated without the lock they are appended under.** `Permittable.on_sensitive_parameter` appends to the sink list under `@registry_mutex`; a contract declaring a `sensitive:` field iterated that same list without it. The GVL hides this on MRI, but on JRuby or TruffleRuby a contract class-loading while a sink is installed is a concurrent mutation during iteration — a raise, or a sink call silently skipped, which is a parameter name that never reaches `config.filter_parameters`. The list is now snapshotted under the mutex and the callbacks run against the snapshot, outside it, so a sink that calls back into the gem cannot deadlock.
+
 ## 0.9.0 (2026-09-27)
 <!-- title: params.expect drafting, audit coverage, field groups, and a rewritten pattern translator -->
 

data/README.md

@@ -297,7 +297,7 @@ Which options are legal depends on the field kind — anything else raises at cl
 | `format:` | ✅¹ | — | — | Regexp the value must match, or a [preset name](#format-presets): `:email`, `:uuid`, `:url`, `:slug`, `:hostname` |
 | `length:` | ✅¹ | ✅ | — | `Range` or `Integer`. Character count on strings, **element count** on arrays, where it short-circuits — see [the field DSL](#the-field-dsl) |
 | `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 either way. On a field with **no** `transform:`, stored as a request sending it would read it — normalized, cast (`default: "18"` on an `:integer` is `18`), an array walked at every depth. On a field **with** `transform:`, stored exactly **as authored** instead — `transform:` never runs on a default (see [output reshaping](#output-reshaping-transform-and-finalize)), and neither does the cast, so the value you write is the value the action receives. Either way it is frozen, and each request gets its own deep copy |
+| `default:` | ✅ | ✅ | — | Value used when the field is absent. Validated against the field's own contract at class load either way. On a field with **no** `transform:`, stored as a request sending it would read it — normalized, cast (`default: "18"` on an `:integer` is `18`), an array walked at every depth with its sub-fields' own `transform:` applied. On a field **with** `transform:`, stored exactly **as authored** instead — `transform:` never runs on a default (see [output reshaping](#output-reshaping-transform-and-finalize)), and neither does the cast, so the value you write is the value the action receives. Either way it is frozen, and each request gets its own deep copy |
 | `validate:` | ✅ | ✅ | — | Callable. Falsy fails as `"invalid"`; a returned `Symbol` becomes the violation code. On an array it runs only when no element violated — an undeclared key inside an element does not count — and `transform:` runs only when nothing violated at all |
 | `transform:` | ✅ | ✅ | — | Callable applied **after** cast and validation — see [output reshaping](#output-reshaping-transform-and-finalize) |
 | `virtual:` | ✅ | ✅ | ✅ | Exempt this field from the schema-drift guard |
@@ -359,9 +359,9 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 | Type | Accepts | Rejects (`invalid_type`) |
 |---|---|---|
 | `:string` | `String`, returned in the encoding it arrived in; `Numeric`/`true`/`false` are stringified | Arrays, hashes, a `String` whose bytes are invalid in its own encoding (`"caf\xC3"`) |
-| `:integer` | `Integer`; whole `Float`s (`4.0`); base-10 numeric strings | `"4.5"`, `"abc"`, `4.5`, NaN/Infinity |
-| `:float` | `Numeric`; any `Float()`-parseable string | `"abc"` |
-| `:decimal` | `Numeric` or `String` → `BigDecimal` | Unparseable strings |
+| `:integer` | `Integer`; whole `Float`s (`4.0`); canonical base-10 numeric strings (`"-12"`, `"007"`) | `"4.5"`, `"abc"`, `"1_8"`, `" 99 "`, `4.5`, NaN/Infinity |
+| `:float` | `Numeric`; a canonical numeric string (`"1.5"`, `".5"`, `"-2e3"`) | `"abc"`, `"1_8.5"`, `" 1.5 "` |
+| `:decimal` | `Numeric`, or a canonical numeric string → `BigDecimal` | Unparseable strings, `"1_000"`, `" 1.5 "` |
 | `:boolean` | `true`/`false`, `"true"`/`"false"`, `"1"`/`"0"`, `1`/`0` | `"yes"`, `"on"`, `2` |
 | `:date` | `Date`; a string naming a **complete** date, in any format `Date.parse` understands (`"2026-09-05"`, `"2026/09/05"`, `"Sep 5, 2026"`) | Unparseable strings, and **incomplete** ones (`"09/2026"`, `"5th"`, `"Sept"`) |
 | `:datetime` | `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, `Date`; a string naming a complete date, with or without a time | Unparseable strings, and any string without a complete date (`"10:30"`) |
@@ -373,6 +373,8 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 
 **Numbers must be finite.** `Float("1e400")` is `Infinity` and `Float("1e-400")` is `0.0` — neither represents what was sent, and neither is a value a numeric column can store, so both are `invalid_type`. A genuine zero is unaffected however it is spelled (`"0"`, `"0.0"`, `"0e10"`). `:decimal` has no exponent limit, so `"1e400"` is fine there — but `BigDecimal("NaN")` and `BigDecimal("Infinity")` *succeed* where `Float()` raises, so those literal strings are rejected explicitly.
 
+**Numbers are spelled the way a client spells them.** `Integer()`, `Float()` and `BigDecimal()` all read underscore digit separators and surrounding whitespace — conveniences for a number literal in Ruby source — so `"1_8"` would be eighteen and `" 99 "` ninety-nine. A numeric string must instead be canonical: an optional sign, digits, an optional fraction and an optional exponent (`"-12"`, `"007"`, `".5"`, `"1.5e10"`). Anything else is `invalid_type`.
+
 Two more behaviours worth committing to memory:
 
 - **Type confusion is a violation, not a 500.** A request of `?age[]=1` against a scalar `:integer` field yields `invalid_type`. Arrays, hashes, and nested `ActionController::Parameters` can never satisfy a scalar type, so the classic "`NoMethodError` on `[]`" crash is impossible.
@@ -572,7 +574,7 @@ The setting is app-wide, not per-contract, because the error format of an API is
 
 Under `:log` that bound is the whole record: nothing else names an undeclared key, so beyond the tenth only the count survives. Where you need every name — auditing what a client really sends during a rollout — use `unknown: :error` in monitor mode, which records all of them in `details` and in the instrumentation payload without rejecting the request.
 
-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 are the route's **path parameters** (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a path parameter rather than a body field); a contract that *declares* `id` has it validated as usual, since the URL really carried it. **ParamsWrapper's copy of a JSON body** under the controller's wrapper key (`user` for `UsersController`) goes further: when Rails made that copy, a rootless contract does not see the key at all, because the client never sent it. So an undeclared wrapper key is not flagged, and a scalar or array field that happens to share the wrapper's name (`optional :feedback, :string` on `FeedbackController`) is simply absent, rather than failing as `invalid_type` against Rails' copy of the whole body. The one exception is a rootless contract that declares the wrapper key as a hash container — a nested block (`required :user do ... end`) or `:json`. That contract is reading the copy on purpose, like a `root:` spelled as a field, so the copy is kept and validated as that field. A client that sends `user` itself is checked like any other key: validated if declared, flagged if not. That holds whether the wrapper name is configured as a String or as a Symbol (`wrap_parameters :user`). Either way `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, a form, nor a request.
+Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token` (or whatever `config.action_controller.request_forgery_protection_token` renames it to), `_method`, `utf8`, and `commit` from an ordinary form POST. All seven are exempt at the top level. So are the route's **path parameters** (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a path parameter rather than a body field); a contract that *declares* `id` has it validated as usual, since the URL really carried it. **ParamsWrapper's copy of a JSON body** under the controller's wrapper key (`user` for `UsersController`) goes further: when Rails made that copy, a rootless contract does not see the key at all, because the client never sent it. So an undeclared wrapper key is not flagged, and a scalar or array field that happens to share the wrapper's name (`optional :feedback, :string` on `FeedbackController`) is simply absent, rather than failing as `invalid_type` against Rails' copy of the whole body. The one exception is a rootless contract that declares the wrapper key as a hash container — a nested block (`required :user do ... end`) or `:json`. That contract is reading the copy on purpose, like a `root:` spelled as a field, so the copy is kept and validated as that field. A client that sends `user` itself is checked like any other key: validated if declared, flagged if not. That holds whether the wrapper name is configured as a String or as a Symbol (`wrap_parameters :user`). Either way `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, a form, nor a request.
 
 All of this changes what is *checked* only. Monitor mode still hands back the form keys, the path parameters and the wrapper's copy in its raw pass-through, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `params[:id]` or `_method` itself; only the router's three are dropped there.
 
@@ -1104,7 +1106,7 @@ A `format:` regexp that does not translate to ECMA-262 is looser in the same way
 | nested block / `array` | `object` + `properties` / `array` + `items` |
 | `unknown: :error` | `additionalProperties: false`, at every nesting level |
 | `root:` | the wrapping object, itself required |
-| `sensitive: true` | `writeOnly: true` (never echoed in responses) |
+| `sensitive: true` | `writeOnly: true` (never echoed in responses); the field's own `default:`/`example:` are omitted rather than published |
 
 </details>
 

data/lib/permittable/authored_values.rb

@@ -3,12 +3,11 @@ module Permittable
   # at class load — the same permittable_check_array a request goes
   # through, so the two cannot drift apart. Two seams are overridden:
   #
-  #   * `transform:` is NOT run. It is app code reshaping a value the client
-  #     sent, and a default is stored as the contract reads it, not as the
-  #     app reshapes it — so a contract with transform: hands out its
-  #     default untransformed, exactly as it always has, and nothing of the
-  #     app's runs at class load beyond the `validate:` an authored value was
-  #     already checked with.
+  #   * the field WHOSE default:/example: is being validated does not run
+  #     its own `transform:` — see permittable_transform below for exactly
+  #     which field that is and why. A SUB-FIELD's own transform: still
+  #     runs, so what gets stored is what an equivalent request would
+  #     produce.
   #   * violations carry no `message:` — they become an ArgumentError for
   #     the contract's author, not a response for a client, and I18n may not
   #     be loaded yet.
@@ -26,6 +25,7 @@ module Permittable
     # [value as a request would get it, violations]
     def read_array(field, value)
       violations = []
+      @field = field
       read = permittable_check_array(field, value, path: field[:name].to_s, unknown: :ignore, violations: violations)
       [read, violations]
     end
@@ -36,8 +36,24 @@ module Permittable
 
     private
 
-    def permittable_transform(_field, value)
-      value
+    # Suppresses transform: for the field WHOSE default/example is being
+    # authored-validated (@field, compared by identity) — never for a
+    # sub-field nested inside it. A sub-field's own transform: is app code
+    # too, but it belongs to a DIFFERENT field's contract: an equivalent
+    # request sending that sub-field's value would run it, so the stored
+    # default has to match, or an omitted field and an explicitly-sent
+    # identical value silently diverge (and the exported OpenAPI default,
+    # which reads this same value, documents one the server never produces).
+    #
+    # When @field itself has a transform:, its result is discarded anyway
+    # (validate_array_authored_value! stores the value AS AUTHORED instead —
+    # see its comment), so nothing inside its subtree is worth reading
+    # transformed: suppressing every nested call too keeps that walk free of
+    # app code, exactly as a scalar default's cast-only check already is.
+    def permittable_transform(field, value)
+      return value if @field[:transform] || field.equal?(@field)
+
+      super
     end
 
     def permittable_violation(_field, param, code)

data/lib/permittable/generator.rb

@@ -400,6 +400,15 @@ module Permittable
     # top (draft_column) must not share this rescue: an error there would
     # otherwise discard EVERY column — the draft silently falls back to a
     # scan alone, or to nothing — for what is one column's problem.
+    #
+    # The rescue is scoped to ActiveRecord::ActiveRecordError, same as
+    # ColumnGuard.schema_reachable? and for the same reason: a genuinely
+    # unreachable schema (no database yet, table not migrated) degrades to
+    # no columns, but a real bug — a broken custom type adapter, a NameError
+    # from a typo — must keep surfacing instead of quietly emitting an empty
+    # draft. The defined? guard keeps this gem loadable without
+    # activerecord, same as schema_reachable? (a host without it duck-types
+    # `model:` and cannot raise an ActiveRecordError in the first place).
     def schema_columns(model)
       return nil unless model.respond_to?(:columns)
       return nil unless model.table_exists?
@@ -408,7 +417,9 @@ module Permittable
       # into its column names; a nil primary key becomes [].
       skipped = SKIPPED_COLUMNS + Array(model.primary_key).map(&:to_s)
       model.columns.reject { |c| skipped.include?(c.name) }
-    rescue StandardError
+    rescue StandardError => e
+      raise unless defined?(ActiveRecord::ActiveRecordError) && e.is_a?(ActiveRecord::ActiveRecordError)
+
       nil
     end
 
@@ -507,7 +518,11 @@ module Permittable
     # can be CALLED as `Model.name`: a `first-status` enum's
     # `Order.first-statuses.keys` parses as `Order.first - statuses.keys`,
     # which runs a query when the draft loads. defined_enums reaches the
-    # same mapping by name.
+    # same mapping by name. The model is also checked for the accessor
+    # itself (mirrors ColumnGuard.enum_keys_expr): a name can pluralize to a
+    # valid identifier that the model does not actually answer to — renamed
+    # or otherwise excluded — and calling it would raise NoMethodError when
+    # the draft loads.
     def enum_for(model, name)
       return nil unless model.respond_to?(:defined_enums)
 
@@ -515,7 +530,11 @@ module Permittable
       return nil unless mapping
 
       plural = name.pluralize
-      accessor = METHOD_NAME.match?(plural) ? "#{model.name}.#{plural}" : "#{model.name}.defined_enums[#{name.inspect}]"
+      accessor = if METHOD_NAME.match?(plural) && model.respond_to?(plural)
+                   "#{model.name}.#{plural}"
+                 else
+                   "#{model.name}.defined_enums[#{name.inspect}]"
+                 end
       { mapping: mapping, accessor: accessor }
     end
 

data/lib/permittable/json_schema.rb

@@ -114,8 +114,16 @@ module Permittable
       schema
     end
 
+    # deep_dup, not dup: .freeze is shallow, so the Array nested in an entry
+    # like :decimal ("type" => %w[string number]) stays live inside the frozen
+    # top-level Hash, and a shallow .dup would hand every :decimal field's
+    # exported schema that SAME Array. Nothing in this file mutates it in
+    # place (nullify! rebinds "type" to a new Array), but the exported
+    # document is caller-owned data, and a caller appending to it would
+    # otherwise silently rewrite the constant for every schema exported
+    # afterward in the process.
     def scalar_schema(field)
-      schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
+      schema = SCALAR_SCHEMAS.fetch(field[:type]).deep_dup
       apply_format_name!(schema, field)
       apply_in!(schema, field)
       apply_string_bounds!(schema, field)
@@ -151,7 +159,11 @@ module Permittable
       min, max = length_bounds(field[:length])
       schema["minItems"] = min if min
       schema["maxItems"] = max if max
-      schema["items"] = field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).dup
+      # deep_dup here for the same reason as scalar_schema: a scalar `of:`
+      # otherwise hands every array field the SAME nested Array/Hash from
+      # SCALAR_SCHEMAS.
+      schema["items"] =
+        field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).deep_dup
       schema
     end
 
@@ -343,10 +355,22 @@ module Permittable
     # (silently changing a value outside any :decimal schema's justification)
     # or coerced through Float, where a non-finite BigDecimal (Infinity, NaN)
     # would crash JSON.generate.
+    #
+    # A `sensitive:` field's `default:`/`example:` are OMITTED rather than
+    # published: this exported document is the one channel meant to leave
+    # the app (client-generator tooling, a public docs endpoint), unlike the
+    # request log a `sensitive:` value is otherwise only redacted from, so
+    # shipping the real value here would defeat the redaction entirely.
+    # Omitting — rather than a placeholder string — matches how every other
+    # untranslatable or opaque fact in this file is handled: left out, with
+    # the `x-permittable-*` extension (here, `writeOnly`/`x-permittable-
+    # sensitive`) as the only signal that something is missing.
     def annotate(schema, field)
       decimal_mode = field[:kind] == JSON_TYPE ? :string : :number
-      schema["default"] = json_value(field[:default], decimal: decimal_mode) if field.key?(:default)
-      schema["examples"] = [json_value(field[:example], decimal: decimal_mode)] if field.key?(:example)
+      unless field[:sensitive]
+        schema["default"] = json_value(field[:default], decimal: decimal_mode) if field.key?(:default)
+        schema["examples"] = [json_value(field[:example], decimal: decimal_mode)] if field.key?(:example)
+      end
       schema["description"] = field[:desc] if field[:desc]
       if field[:sensitive]
         schema["writeOnly"] = true

data/lib/permittable/open_api.rb

@@ -115,8 +115,16 @@ module Permittable
       Permittable.error_format == :problem
     end
 
+    # ERROR_SCHEMA/PROBLEM_SCHEMA are frozen, but `.freeze` is shallow — only
+    # the top-level Hash is frozen, not the Hashes nested inside it — so
+    # handing either constant out by reference let a caller mutate a nested
+    # level of ITS document and permanently corrupt the shared constant for
+    # every document generated for the rest of the process. `deep_dup` (the
+    # same ActiveSupport helper the contract registry uses to copy authored
+    # default:/example: values before freezing, see permittable.rb) gives
+    # every caller its own independent copy instead.
     def error_schema
-      problem_format? ? PROBLEM_SCHEMA : ERROR_SCHEMA
+      (problem_format? ? PROBLEM_SCHEMA : ERROR_SCHEMA).deep_dup
     end
 
     def error_media_type

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.9.0".freeze
+  VERSION = "0.10.0".freeze
 end

data/lib/permittable.rb

@@ -403,7 +403,14 @@ module Permittable
       # 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?
+      unless name.empty?
+        # sensitive_parameter_sinks is the same process-global Array
+        # on_sensitive_parameter appends to under @registry_mutex. Reading it
+        # here without that lock is an unsynchronized concurrent mutation
+        # during iteration on any Ruby without a GVL — a thread class-loading
+        # a sensitive: true contract can race a thread installing a sink.
+        @registry_mutex.synchronize { sensitive_parameter_sinks.dup }.each { |sink| sink.call(name) }
+      end
       nil
     end
 
@@ -744,6 +751,17 @@ module Permittable
       end
     end
 
+    # Kernel#Integer/Float and BigDecimal() all accept underscore digit
+    # separators and surrounding whitespace — a convenience for a NUMBER
+    # LITERAL IN RUBY SOURCE, not for a request body. "1_8" is not how a
+    # client spells eighteen, and " 99 " is not how one spells ninety-nine;
+    # silently accepting either is the same kind of leniency as the
+    # NaN/Infinity/`0e10` cases below, just arriving from a different door.
+    # Checked against the raw String before any of those delegate, so a
+    # non-canonical spelling never reaches them at all.
+    INTEGER_FORMAT = /\A[+-]?\d+\z/
+    NUMERIC_FORMAT = /\A[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?\z/
+
     def cast_integer(value)
       case value
       when Integer then [:ok, value]
@@ -751,7 +769,7 @@ module Permittable
       # RangeError, which the ArgumentError rescue below does not catch), and
       # no integer is what either one sent. Same rule as finite_float.
       when Float then value.finite? && value == value.truncate ? [:ok, value.to_i] : [:error, "invalid_type"]
-      when String then [:ok, Integer(value, 10)]
+      when String then value.match?(INTEGER_FORMAT) ? [:ok, Integer(value, 10)] : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
@@ -761,7 +779,7 @@ module Permittable
     def cast_float(value)
       case value
       when Numeric then finite_float(value.to_f)
-      when String then finite_float(Float(value), source: value)
+      when String then value.match?(NUMERIC_FORMAT) ? finite_float(Float(value), source: value) : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
@@ -792,7 +810,8 @@ module Permittable
 
     def cast_decimal(value)
       case value
-      when Numeric, String then finite_decimal(BigDecimal(value.to_s))
+      when Numeric then finite_decimal(BigDecimal(value.to_s))
+      when String then value.match?(NUMERIC_FORMAT) ? finite_decimal(BigDecimal(value)) : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
@@ -1561,8 +1580,10 @@ module Permittable
     # gets); with one, the array exactly AS AUTHORED — the walker still runs,
     # so a declaration mistake (an element `validate:` refuses, a sub-field
     # default out of bounds) still fails at class load, but its cast result
-    # is discarded rather than stored. `transform:` itself is deliberately
-    # never run on a default either way — see AuthoredValues.
+    # is discarded rather than stored. The array's OWN `transform:` is
+    # deliberately never run on a default either way; a SUB-FIELD's
+    # `transform:` still runs during that walk, so "the walker's read" above
+    # really is what an equivalent request produces — see AuthoredValues.
     def validate_array_authored_value!(field, opt)
       value = field[opt]
       return if authored_nil!(field, opt)
@@ -1621,7 +1642,11 @@ module Permittable
     def validate_message!(field)
       spec = field[:message]
       return if spec.nil?
-      return if spec.is_a?(String)
+
+      if spec.is_a?(String)
+        field[:message] = freeze_authored(spec)
+        return
+      end
 
       valid_hash = spec.is_a?(Hash) && !spec.empty? &&
                    spec.all? { |code, text| (code.is_a?(Symbol) || code.is_a?(String)) && text.is_a?(String) }
@@ -1630,7 +1655,7 @@ module Permittable
                              "or a Hash of violation code => String (e.g. { missing: \"is required\" })"
       end
 
-      field[:message] = spec.transform_keys(&:to_sym).freeze
+      field[:message] = freeze_authored(spec.transform_keys(&:to_sym))
     end
   end
 
@@ -2357,7 +2382,10 @@ module Permittable
 
     declared = fields.map { |f| f[:name].to_s }
     extra = hash.keys.map(&:to_s) - declared
-    extra -= UNCHECKED_TOP_LEVEL_KEYS + permittable_request_supplied_keys if top_level
+    if top_level
+      extra -= UNCHECKED_TOP_LEVEL_KEYS + permittable_request_supplied_keys
+      extra -= [permittable_configured_csrf_key].compact
+    end
     return if extra.empty?
 
     if unknown == :error
@@ -2382,6 +2410,25 @@ module Permittable
     request.path_parameters.keys.map(&:to_s)
   end
 
+  # FORM_KEYS bakes in "authenticity_token" — Rails' DEFAULT CSRF parameter
+  # name — but `config.action_controller.request_forgery_protection_token`
+  # lets an app rename it, and an app that does trips `unknown: :error` on
+  # every ordinary form submission: exactly the bug FORM_KEYS exists to
+  # prevent, just spelled with the app's own key instead of the default one.
+  # The configured name isn't knowable at class-load time (it can vary per
+  # controller, and Rails may not have finished initializing yet), so it's
+  # read fresh here off the live controller instead of folded into a frozen
+  # constant. `request_forgery_protection_token` comes from
+  # ActionController::RequestForgeryProtection, included by ActionController
+  # ::Base; a plain params duck or a standalone Contract has no such method
+  # and exempts nothing beyond FORM_KEYS's own "authenticity_token".
+  def permittable_configured_csrf_key
+    return nil unless respond_to?(:request_forgery_protection_token)
+
+    token = request_forgery_protection_token
+    token && token.to_s
+  end
+
   # A rootless contract's input without ParamsWrapper's copy of the body,
   # when Rails made one (see process_action). Removed rather than merely
   # exempted from the unknown-keys check, because the client never sent that

metadata

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