clickwrap 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f77c92e4ac5400a7c7fba781bd2a592875f3deef59fd8b3c1d6269e302ffc6
-  data.tar.gz: f15af7f288d8349bc8cd322b28b472e68bca750a8c17718648d7fa2db3877021
+  metadata.gz: 1ea29dba21d2740876c9708ad687520310951911eab737844b59577fbbe24464
+  data.tar.gz: 01140025f14f2c137ba35a25ab694898d31fdbc719a42a488d63204007b0dc85
 SHA512:
-  metadata.gz: fceb30a214fe8e4cdfcc19a775f8082fefe61424eba2e463958240dec07a0c8d099e1d3c6e5e0b9d67bd47eb11a445ee591f4b520c08f847479fbed277f197f2
-  data.tar.gz: e8d53673c7a5d9ba553078ace895a187e404b6a486525ee56d362f584e262f3bb9f9000287bf57311b22a40e2049140867f5eefdb300e945a7d69d25ff31dcf4
+  metadata.gz: 752ed3dda0897564843222843c444a9c5c945493152ec04e697241871afda8df0eeea9635b3f07296a392f58c46abe763366daa759f0916cd5bb455f56a04e01
+  data.tar.gz: 71e5c6512a165734f941b7e5483b399e8d46e83a3963e05af5ae2d3e077dbcf4eac0b0e7eddebc9ff61b7a9d3b73c551502fb434388c65c1830e2b75a6e0add1

data/CHANGELOG.md

@@ -6,6 +6,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/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.2"
 
   # 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickwrap
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - rameerez