clickwrap 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f77c92e4ac5400a7c7fba781bd2a592875f3deef59fd8b3c1d6269e302ffc6
-  data.tar.gz: f15af7f288d8349bc8cd322b28b472e68bca750a8c17718648d7fa2db3877021
+  metadata.gz: 4e284e0a7a0474b4dc4d3031424074d45c06dfb3f4432d78a3c64c2ec9ca77ba
+  data.tar.gz: 1b09f1436d6f8b18bcfb7f39b4f4f33e311438bb79a020a6b9f47c777cdada15
 SHA512:
-  metadata.gz: fceb30a214fe8e4cdfcc19a775f8082fefe61424eba2e463958240dec07a0c8d099e1d3c6e5e0b9d67bd47eb11a445ee591f4b520c08f847479fbed277f197f2
-  data.tar.gz: e8d53673c7a5d9ba553078ace895a187e404b6a486525ee56d362f584e262f3bb9f9000287bf57311b22a40e2049140867f5eefdb300e945a7d69d25ff31dcf4
+  metadata.gz: 1778cebf0236280efaab60e63ec3f6591742e12188c27c152923d6ee58ad1eb04bc71c74b14f1b606ed93ea3212d8f307fc31e284db0a595235f20848311907e
+  data.tar.gz: 653515517233ee6b0d94245098c0d5dff6bd48cf3c708183b86158c9147a579aeac9ab345d5b52eda9ac7d53fc8f291feedfc2e286291da26a38fe123cf88f0e

data/CHANGELOG.md

@@ -6,6 +6,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-08-31
+
+### Fixed — the actor class survives a reload
+
+- **`config.actor_class` followed the constant it had cached, not the one the
+  app has.** In a Rails app with reloading, every capture after the first code
+  change of a session raised
+
+  ```
+  Clickwrap was asked to record User as the actor, but
+  `config.actor_class_name` says the records that can act are User.
+  ```
+
+  Both halves name the same class, which reads as a contradiction and sends
+  whoever hits it to an initializer that is correct. They were two different
+  Ruby objects printing the same name: `actor_class` memoized the
+  constantized `Class` and re-resolved only when the class NAME changed —
+  which never happens, since the name is set once in an initializer — while
+  Zeitwerk replaces the class behind that name on every edit. The cache then
+  held a class no living record was an instance of, so
+  `actor.is_a?(config.actor_class)` was false for an ordinary `User` and
+  capture refused to record it.
+
+  The memo is gone. `constantize` after the first load is a `const_get` and
+  this is called once per capture rather than in a loop, so it was never
+  buying anything; `parent_controller_class` has always resolved this way.
+  Production was never affected — classes are not reloaded there — but every
+  development session was, from its second edit onwards.
+
+## [0.3.2] - 2026-08-20
+
+### Fixed — two guards that looked like they held
+
+- **Canonical JSON refuses invalid bytes whatever their encoding tag.**
+  `valid_encoding?` is always true on an `ASCII-8BIT` string — BINARY has no
+  invalid byte sequences by definition — and BINARY is exactly what Rack and
+  CDN headers deliver, so the UTF-8 guard was a no-op for the ten
+  request-evidence values most likely to be malformed. Invalid bytes passed
+  through and produced canonical JSON that was not itself valid UTF-8, which
+  RFC 8785 forbids and a verifier in another language may reject or normalize
+  into a different digest. The guard now normalizes the tag before validating.
+  **No digest ever written changes**: bytes that are valid UTF-8 canonicalize
+  byte-identically whether they arrive tagged BINARY or UTF-8, which a test
+  pins. And a stored value that can no longer be canonicalized now reports a
+  binding mismatch instead of raising out of the integrity check — a check
+  that crashes tells an operator nothing except that the tool broke.
+- **`record_ip_geolocation(country: nil)` is refused instead of quietly
+  enabling three fields.** With plain `nil` keyword defaults an explicit nil
+  was indistinguishable from an omitted keyword, so a policy written as
+  `record_ip_geolocation(country: settings[:geo])` with an empty setting fell
+  through to the coarse-trio default — enabling a category of personal data as
+  a side effect, which the frictionless pass never relaxed. A sentinel now
+  tells the two apart: unmentioned still gets the coarse trio, `false` still
+  reaches the coherence check that names `do_not_record_ip_geolocation`, and
+  `nil` raises a sentence.
+- **A scaffolding `legal_basis_reference:` is refused like a scaffolding
+  `because:`.** The reference lands in the compiled policy revision and every
+  receipt built from it, permanently, where "TODO: ask legal" reads as a
+  reviewed determination rather than an omission. The option stays optional;
+  text the host actually wrote has to be text they meant.
+
+### Documentation
+
+- The installer's purpose and retention prompts now describe what the
+  installer actually does since 0.3.x: a blank purpose is accepted (the gem
+  records its own stated purpose, marked as the gem's), a blank period keeps
+  pace with the evidence it corroborates, and only scaffolding text or a
+  negative period stops generation.
+
 ## [0.3.1] - 2026-08-20
 
 ### Changed — the rest of the collection friction, and the principle behind removing it

data/guides/migrating.md

@@ -333,3 +333,26 @@ never satisfy a human-action predicate.)
 | [FinePrint README at the audited commit](https://github.com/openstax/fine_print/blob/3b75fbcbcfb048ecd2f4ee7c4f0b9bd3d10f7603/README.md#L7-L25) | Pinned source code |
 | [FinePrint signature model at the audited commit](https://github.com/openstax/fine_print/blob/3b75fbcbcfb048ecd2f4ee7c4f0b9bd3d10f7603/app/models/fine_print/signature.rb#L1-L33) | Pinned source code |
 | The never-synthesize rule, the `unknown:` vocabulary, and the dry-run-first workflow | Product-design inference |
+
+## Completeness: enumerate writers, not rows
+
+A migration inventory built by looking at what the database HOLDS will miss
+what the code can WRITE. One production integration classified 52 distinct
+audit event types from its data — the codebase carried ~150: everything rare
+(incident and recovery paths that had never fired) and everything new
+(writers added after the cutover) was invisible to the data-only sweep, and
+one of the missed stores turned out to hold the product's most consequential
+assent act.
+
+Sweep three ways, and reconcile the lists:
+
+1. **Schema**: every table and column whose name says assent — accepted,
+   declared, consent, attest, authoriz, acknowledg, signed.
+2. **Writers**: every place code can create such a record — grep the literals
+   (`event_type:`, ledger inserts), not the rows.
+3. **Structure**: every model already carrying `has_clickwrap_evidence`, and
+   every dual-write site.
+
+Then write a disposition for every entry — import it, "not a clickwrap" with
+the reason, or "provider record" — in a tracked document. Silently ignoring a
+store is not a valid disposition.

data/guides/request-evidence.md

@@ -575,3 +575,27 @@ can never undo or stand in for the Clickwrap event. Clickwrap ships no Footprint
 | [Trackdown v0.4.0 result object](https://github.com/rameerez/trackdown/blob/v0.4.0/lib/trackdown/location_result.rb), [configuration](https://github.com/rameerez/trackdown/blob/v0.4.0/lib/trackdown/configuration.rb), [Cloudflare provider](https://github.com/rameerez/trackdown/blob/v0.4.0/lib/trackdown/providers/cloudflare_provider.rb), [MaxMind provider](https://github.com/rameerez/trackdown/blob/v0.4.0/lib/trackdown/providers/maxmind_provider.rb), [PR #9](https://github.com/rameerez/trackdown/pull/9) | Pinned released source and project change record |
 | [Footprinted pinned model](https://github.com/rameerez/footprinted/blob/03b714bd3fa31368a8ce6695433386128fb6f91c/lib/footprinted/footprint.rb#L7-L52), [tracking concern](https://github.com/rameerez/footprinted/blob/03b714bd3fa31368a8ce6695433386128fb6f91c/lib/footprinted/model.rb#L7-L65) | Pinned source code |
 | The field selection, the ordering of evidentiary priority, and every API prescription above | Product-design inference |
+
+## Rendering recorded values: encodings survive encryption
+
+Rack hands header strings to Ruby tagged `ASCII-8BIT`, and encrypted
+attributes preserve the original encoding through decryption — so a recorded
+`browser_user_agent` read back from the annex is BINARY-tagged even when its
+bytes are perfectly valid UTF-8. Concatenating it into a UTF-8 view buffer
+raises `Encoding::CompatibilityError`, and because only live captures carry
+an annex, the failure hides until the first real signup reaches an admin
+screen (it took down a production operator panel exactly that way).
+
+Normalize at the render boundary, not in storage — the stored bytes are the
+evidence:
+
+```ruby
+# clickwrap-doc-test: syntax-only — a host view helper, not gem configuration
+def rendered_recorded_text(value)
+  utf8 = value.to_s.dup.force_encoding(Encoding::UTF_8)
+  utf8.valid_encoding? ? utf8 : utf8.scrub
+end
+```
+
+The gem's own screens never render raw annex values, so they are not exposed;
+any host view that does — an operator panel, an export page — is.

data/lib/clickwrap/canonical_json.rb

@@ -132,10 +132,26 @@ module Clickwrap
       end
 
       def write_string(string, buffer)
-        raise SerializationError, "Canonical JSON strings must be valid UTF-8" unless string.valid_encoding?
+        # `valid_encoding?` is ALWAYS true on an ASCII-8BIT string — BINARY has
+        # no invalid byte sequences by definition — and BINARY is exactly what
+        # Rack and CDN headers deliver, so this guard was a no-op for the
+        # strings most likely to be malformed. Ten request-evidence columns
+        # reach it.
+        #
+        # Normalizing the tag before validating is safe for every digest ever
+        # written: bytes that ARE valid UTF-8 canonicalize byte-identically
+        # whether they arrive tagged BINARY or UTF-8 (measured, and pinned by a
+        # test below). What changes is only the case that was broken —
+        # genuinely invalid bytes used to emit canonical JSON that was itself
+        # not valid UTF-8, which RFC 8785 forbids and a verifier in another
+        # language may reject or normalize into a different digest. That is the
+        # "still verifiable years later" promise failing silently, so it is
+        # refused at write time instead.
+        utf8 = string.encoding == Encoding::UTF_8 ? string : string.dup.force_encoding(Encoding::UTF_8)
+        raise SerializationError, "Canonical JSON strings must be valid UTF-8" unless utf8.valid_encoding?
 
         buffer << '"'
-        string.each_char do |char|
+        utf8.each_char do |char|
           escape = ESCAPES[char]
           buffer << if escape
                       escape

data/lib/clickwrap/configuration.rb

@@ -307,16 +307,29 @@ module Clickwrap
       @describe_authentication_with = ensure_callable(value, "describe_authentication_with")
     end
 
-    # The constantized actor class, resolved lazily on first use. Lazy on
-    # purpose: the initializer that sets `config.actor_class_name = "User"` runs
-    # before the User model is necessarily loaded.
+    # The constantized actor class, resolved lazily on EVERY use. Lazy on
+    # purpose: the initializer that sets `config.actor_class_name = "User"`
+    # runs before the User model is necessarily loaded.
+    #
+    # Not memoized, deliberately. This used to cache the resolved Class object
+    # and re-resolve only when the class NAME changed — which is never, since
+    # the name is set once in an initializer. In a Rails app with reloading,
+    # the class behind that name is replaced on every code change: Zeitwerk
+    # unloads the old User and defines a new one, same name, different object.
+    # The cache then held a class no living record was an instance of, and
+    # `actor.is_a?(config.actor_class)` failed for a perfectly ordinary User.
+    #
+    # What that looked like from the outside was worse than the bug: the
+    # ConfigurationError names the offending class and the configured class,
+    # and both printed "User". The message read as a contradiction, sent
+    # people to an initializer that was correct, and came back after every
+    # edit — the first signup of a dev session worked and the second did not.
+    #
+    # `constantize` after the first load is a const_get, and this is called
+    # once per capture rather than in a loop, so there was nothing to save.
+    # `parent_controller_class` below has always resolved this way.
     def actor_class
-      name = actor_class_name
-      if @actor_class.nil? || @actor_class_name_at_resolution != name
-        @actor_class = name.constantize
-        @actor_class_name_at_resolution = name
-      end
-      @actor_class
+      actor_class_name.constantize
     end
 
     def parent_controller_class = parent_controller_class_name.constantize

data/lib/clickwrap/dsl/policy_builder.rb

@@ -257,9 +257,21 @@ module Clickwrap
       # and nothing finer, because that is what "IP geolocation" means in this
       # gem when nobody narrows it. Naming even one field means you are
       # choosing the set yourself, and then the set is exactly what you named.
-      def record_ip_geolocation(country: nil, region: nil, city: nil, postal_code: nil,
-                                latitude_and_longitude: nil, timezone: nil, continent: nil,
-                                metro_code: nil, accuracy_radius_in_kilometers: nil,
+      # Distinguishes "the policy never mentioned this field" from "the policy
+      # passed nil for it". With plain `nil` defaults the two are identical, and
+      # `record_ip_geolocation(country: settings[:geo])` with an empty setting
+      # silently enabled the coarse trio — enabling a category of personal data
+      # as a side effect, which is the one thing the frictionless pass never
+      # relaxed.
+      UNMENTIONED_FIELD = Object.new.freeze
+      private_constant :UNMENTIONED_FIELD
+
+      def record_ip_geolocation(country: UNMENTIONED_FIELD, region: UNMENTIONED_FIELD,
+                                city: UNMENTIONED_FIELD, postal_code: UNMENTIONED_FIELD,
+                                latitude_and_longitude: UNMENTIONED_FIELD,
+                                timezone: UNMENTIONED_FIELD, continent: UNMENTIONED_FIELD,
+                                metro_code: UNMENTIONED_FIELD,
+                                accuracy_radius_in_kilometers: UNMENTIONED_FIELD,
                                 using: nil, encrypted: nil, delete_after: nil, retain_until: nil,
                                 fail_if_unavailable: false, because: nil,
                                 legal_basis_reference: nil,
@@ -415,14 +427,28 @@ module Clickwrap
         end
       end
 
-      # `nil` means "the policy did not mention this field"; `false` means "the
-      # policy named it and turned it off". The distinction is the whole reason
-      # the keywords default to nil: a policy that mentions nothing gets the
-      # coarse trio, and a policy that explicitly sets every field to false
-      # still reaches the coherence check that tells it to say
+      # An UNMENTIONED field means "the policy did not mention this"; `false`
+      # means "the policy named it and turned it off". A policy that mentions
+      # nothing gets the coarse trio; a policy that explicitly sets every field
+      # to false still reaches the coherence check that tells it to say
       # `do_not_record_ip_geolocation` instead.
+      #
+      # An explicit `nil` is neither, and is refused rather than guessed: it is
+      # almost always a variable that came out empty, and treating it as "the
+      # policy said nothing" would turn a missing setting into three enabled
+      # fields of personal data.
       def default_ip_geolocation_fields_when_none_named(named)
-        return named.transform_values { |value| value == true } if named.any? { |_, value| !value.nil? }
+        ambiguous = named.select { |_, value| value.nil? }.keys
+        unless ambiguous.empty?
+          raise DefinitionError,
+                "Policy #{@key} passes nil for #{ambiguous.join(", ")} in " \
+                "`record_ip_geolocation`. Say `true` or `false` for each field you name, " \
+                "or leave it out entirely — Clickwrap will not read an empty value as " \
+                "permission to record it, and it will not read it as silence either."
+        end
+
+        mentioned = named.reject { |_, value| value.equal?(UNMENTIONED_FIELD) }
+        return named.transform_values { |value| value == true } if mentioned.any?
 
         Vocabulary::IP_GEOLOCATION_DATA_FIELDS.to_h do |field|
           [field, Vocabulary::COARSE_IP_GEOLOCATION_DATA_FIELDS.include?(field)]

data/lib/clickwrap/models/request_evidence.rb

@@ -302,11 +302,18 @@ module Clickwrap
       key = Clickwrap.config.request_evidence_binding_key_for(key_id)
       return false if key.nil?
 
-      computed = Digest.keyed_digest(
-        CanonicalJson.generate(binding_body_for(category)),
-        key: key,
-        algorithm: digest_algorithm
-      )
+      # A stored value that can no longer be canonicalized cannot reproduce its
+      # binding, and saying so is the honest answer — an integrity check that
+      # raises tells an operator nothing except that the tool broke.
+      begin
+        computed = Digest.keyed_digest(
+          CanonicalJson.generate(binding_body_for(category)),
+          key: key,
+          algorithm: digest_algorithm
+        )
+      rescue CanonicalJson::SerializationError
+        return false
+      end
       Digest.secure_compare?(computed, digest)
     end
 

data/lib/clickwrap/request_evidence_policy.rb

@@ -229,6 +229,20 @@ module Clickwrap
               "purpose."
       end
 
+      # The legal-basis reference goes into the compiled policy revision and
+      # every receipt built from it, permanently. Scaffolding there is worse
+      # than an omission: an omission reads as "the host said nothing", while
+      # "TODO: ask legal" reads as a reviewed determination to anyone who finds
+      # it later. Same rule as `because:` — the option is optional, but text
+      # the host actually wrote has to be text they meant.
+      if ReviewedText.placeholder?(setting.legal_basis_reference)
+        raise DefinitionError,
+              "Policy #{policy_key} records #{category} with a `legal_basis_reference:` " \
+              "that is still scaffolding text (#{setting.legal_basis_reference.inspect}). " \
+              "Replace it with the application's own reference, or drop the option — " \
+              "Clickwrap would rather record nothing than record a TODO as a legal basis."
+      end
+
       return unless setting.delete_after && setting.delete_after.to_i <= 0
 
       raise DefinitionError,

data/lib/clickwrap/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Clickwrap
-  VERSION = "0.3.1"
+  VERSION = "0.3.3"
 
   # The canonical schema version for receipts, event digests, and presentation
   # manifests. This is deliberately independent of VERSION: gem releases may

data/lib/generators/clickwrap/install_generator.rb

@@ -980,15 +980,18 @@ module Clickwrap
 
       def ask_purpose(label)
         say "\n  Why does the application need #{label}? One plain sentence, in your own"
-        say "  words — it goes into the initializer and the privacy inventory. A blank"
-        say "  or scaffolding answer stops generation before Clickwrap writes any files."
+        say "  words — it goes into the initializer and the privacy inventory. Leave it"
+        say "  blank and Clickwrap records its own stated purpose instead, marked as the"
+        say "  gem's; a scaffolding answer (TODO, FIXME) stops generation before any"
+        say "  files are written."
         ask("  Purpose:").to_s.strip
       end
 
       def ask_retention_days(label)
         say "\n  After how many days should Clickwrap delete #{label}?"
-        say "  Clickwrap does not invent a period. Enter the positive number your application"
-        say "  has reviewed; a blank or zero answer stops generation before files are written."
+        say "  Enter the number of days your application reviewed, or leave it blank and"
+        say "  #{label} keeps pace with the evidence it corroborates — kept until a"
+        say "  reviewed disposition removes it. A negative number stops generation."
         ask("  Days:").to_s.strip.to_i
       end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: clickwrap
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack