clickwrap 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 504024fe0e6e146a907899092e9da9fe3f62501a2d2b251cb0f190cc72516860
-  data.tar.gz: 542284305afe7e79d11e5759ce2c88630982ce7ad0862866a58a50824056b4d8
+  metadata.gz: 1ea29dba21d2740876c9708ad687520310951911eab737844b59577fbbe24464
+  data.tar.gz: 01140025f14f2c137ba35a25ab694898d31fdbc719a42a488d63204007b0dc85
 SHA512:
-  metadata.gz: 34500cc2c493a726afa16ed51e592102109bf56750eeb19a67624b85d0565d98ec316f45ac8653ffe2aa6f757c690577d37b34b986c71e8f5cd95fa766648b6c
-  data.tar.gz: 5ed6946bb7aa2319a3f27b11c40ff79a64d85759353567b1e46be342e7966e7f180eda5be79acf9229c156d5bbcf9397e2ad473184947dce2e64ec577bd615cb
+  metadata.gz: 752ed3dda0897564843222843c444a9c5c945493152ec04e697241871afda8df0eeea9635b3f07296a392f58c46abe763366daa759f0916cd5bb455f56a04e01
+  data.tar.gz: 71e5c6512a165734f941b7e5483b399e8d46e83a3963e05af5ae2d3e077dbcf4eac0b0e7eddebc9ff61b7a9d3b73c551502fb434388c65c1830e2b75a6e0add1

data/CHANGELOG.md

@@ -6,6 +6,137 @@ 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
+
+0.3.0 made *enabling* request evidence one switch and gave the initializer
+defaults honest gem-supplied purposes. It left the friction standing
+everywhere else: a policy-level `record_ip_address` still read as though it
+wanted a sentence, `record_ip_geolocation` refused to do anything without a
+field list, and the encryption escape hatch still demanded a reason be
+phrased twice. This finishes the job the owner asked for.
+
+The principle, in their words: **the host application and its privacy policy
+own *why* data is collected; this gem records *what* was collected, honestly,
+and is nobody's nanny.** Its job is evidence mechanics, not gatekeeping
+collection. Everything below now works exactly as written:
+
+```ruby
+Clickwrap.configure do |config|
+  config.record_request_evidence_by_default = true
+  config.keep_recorded_ip_addresses_indefinitely!
+  config.deliberately_store_request_evidence_unencrypted!
+end
+
+Clickwrap.policy :anything do
+  agree_to :terms
+  record_ip_address
+  record_browser_user_agent
+  record_ip_geolocation
+end
+```
+
+- **All three `record_` verbs take zero keyword arguments.** `because:`,
+  `legal_basis_reference:`, `data_protection_impact_assessment_reference:`,
+  `delete_after:`, `retain_until:`, and `encrypted:` are optional in fact and
+  not merely in the signature — nothing downstream refuses their absence.
+  (`legal_basis_reference` and the DPIA reference never were required anywhere
+  in the gem; a test now pins that they never become so.)
+- **`record_ip_geolocation` with no field named records the coarse trio** —
+  country, region, city — the same set `record_request_evidence_by_default`
+  turns on, and nothing finer. The field keywords moved from `false` to `nil`
+  defaults so "did not mention this field" is distinguishable from "named it
+  and turned it off". Naming even one field means you are choosing the set
+  yourself, and the set is exactly what you named. Naming every field `false`
+  is still refused, because calling the verb and disabling everything cannot
+  mean anything; `do_not_record_ip_geolocation` is how to say that.
+- **`keep_recorded_{ip_addresses,browser_user_agents,ip_geolocation}_indefinitely!`
+  take no arguments at all.**
+- **`deliberately_store_request_evidence_unencrypted!` no longer needs a
+  `because:`.** The method NAME is the ceremony: `encrypt_recorded_* = false`
+  still cannot be reached without writing that line, and a reviewer still
+  finds it in the diff. When the host writes no reason the gem records
+  `Vocabulary::DEFAULT_REASON_FOR_STORING_REQUEST_EVIDENCE_UNENCRYPTED`.
+  Encryption itself is untouched — on by default for all three categories,
+  with a test pinning that the one switch does not weaken it.
+- **The install generator stops refusing an incomplete category.**
+  `--record-ip-addresses-by-default` with no reason and no period writes the
+  file and simply omits those two lines, so the gem's own defaults apply.
+- The `ReviewedText` placeholder check now only ever applies to text a host
+  actually supplied. Absence is never scaffolding.
+
+### Unchanged, deliberately
+
+- Reasons that are not about *collection* keep their required `because:`:
+  `delete_recorded_ip_address!` and its siblings, `dispose_core_event!`,
+  `place_on_legal_hold!` / `release_legal_hold!`, `plan_disposition_for`,
+  unredacted receipt export, and the lifecycle verbs. Those record a
+  destructive act, an access, or a state change — there the audit trail *is*
+  the reason, and there is no honest default for "why did somebody delete
+  this".
+- Still refused, because each is the host contradicting themselves rather than
+  leaving a blank: scaffolding text the host actually wrote standing in for a
+  purpose (including in the installer, where a `TODO` in a shipped initializer
+  is worse than no line and the gem would reject it at boot anyway), a
+  negative deletion period passed to the installer, a deletion clock declared
+  alongside `keep_recorded_..._indefinitely!` for the same category, and
+  `record_ip_geolocation` with every field explicitly off.
+- The gem's code default is still record-nothing. Claim boundaries, receipt
+  state labeling (`not_configured` / `unavailable` / `recorded` /
+  `deleted_after_retention`), and every released receipt format are untouched.
+
+### Documentation
+
+- README, `guides/request-evidence.md`, and `guides/naming.md` show the
+  zero-keyword forms as the ordinary way to write a policy, with purposes,
+  legal bases, and clocks as the upgrade path.
+- `CLAUDE.md` / `AGENTS.md` rule 6 is rewritten around the principle above and
+  records the owner directive and its date. What it keeps as non-negotiable:
+  never a switch whose NAME hides what it collects, never an overclaim, never
+  a blurred receipt state, encryption on by default behind its named call,
+  host-supplied scaffolding rejected, and contradictions refused.
+
 ## [0.3.0] - 2026-08-20
 
 ### Changed — recording request evidence is one switch, not a checklist

data/README.md

@@ -733,7 +733,7 @@ end
 
 That records, on every policy: the IP address the request arrived from, the browser user agent it sent, and a coarse country / region / city estimate for that address. Add [`trackdown`](https://github.com/rameerez/trackdown) 0.4+ to your Gemfile and the geolocation half resolves itself — Clickwrap picks up the official adapter with no wiring line, so trackdown plus Cloudflare genuinely is "bundle it and flip the switch".
 
-Nothing else is required, because Clickwrap supplies honest defaults for the parts you did not write:
+Nothing else is required — anywhere, at either level. **Your privacy policy owns the why; the gem records the what, honestly, and is nobody's nanny.** Clickwrap supplies its own defaults for every part you did not write:
 
 - **Purpose.** Every recorded field carries one into the receipt. Yours if you wrote one, otherwise Clickwrap's: *"Corroborate who performed each recorded act, from where, on what client — to defend the recorded agreement itself."* The [privacy inventory](#operations) marks which of the two it is reading back (`"purpose_source": "gem_default"` vs `"host"`), so a gem sentence never passes for a decision your team reviewed.
 - **How long.** No clock means it keeps pace with the evidence it corroborates — the same posture core evidence has had since 0.2.0. A corroboration scheduled to expire before the agreement it corroborates is a scheduled weakening of the record.
@@ -772,7 +772,23 @@ end
 
 Two things are still refused, and both are you contradicting yourself rather than leaving a blank: scaffolding text (`"TODO: ask legal"`) standing in for a purpose, and a deletion clock set alongside `keep_recorded_..._indefinitely!` for the same category.
 
-A single regulated surface can also name a field per policy instead of by default:
+### Per policy, with as much or as little as you want
+
+A single surface can name the fields itself instead of inheriting the default. The frictionless form takes no arguments at all:
+
+```ruby
+Clickwrap.policy :withdrawal_authorization do
+  authorize :regulated_action, one_time: true, valid_for: 10.minutes
+
+  record_ip_address
+  record_browser_user_agent
+  record_ip_geolocation
+end
+```
+
+`record_ip_geolocation` with no field named records the same coarse trio as the switch — country, region, city. Name even one field and you are choosing the set yourself, and the set is exactly what you named.
+
+The same declarations with the full record a reviewed team would want:
 
 ```ruby
 Clickwrap.policy :regulated_authorization do
@@ -791,9 +807,11 @@ end
 Recorded values live in a separately encrypted annex with their own retention, so
 they can be deleted later without rewriting the core event payload. Core payloads
 have their own reviewed disposition path and leave a digest-linked tombstone.
-Encryption is on by default and turning it off keeps its own ceremony —
-`config.deliberately_store_request_evidence_unencrypted!(because: "…")` — because
-that one is a real hazard, not paperwork.
+Encryption is on by default for all three categories. Turning it off keeps its
+own ceremony — you cannot reach `encrypt_recorded_ip_addresses = false` without
+first writing `config.deliberately_store_request_evidence_unencrypted!` — but the
+ceremony is the method name a reviewer finds in the diff, not a sentence the gem
+makes you type. `because:` there is optional too.
 
 For IP geolocation, [`trackdown`](https://github.com/rameerez/trackdown) 0.4 or newer is the official resolver, and Clickwrap uses it automatically when your bundle has it and you named no resolver of your own. Set it explicitly when you want a different provider per policy, or when you are wiring Trackdown's per-request CDN trust:
 

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/naming.md

@@ -291,7 +291,7 @@ object.
 | `chain_event_history_with`, `anchor_event_history_with`, `timestamp_receipts_with` | one `integrity_level` setting | Three different mechanisms making three different claims. One setting would let a reader infer the strongest from the presence of the weakest |
 | `after_event_is_committed` | `after_commit` | Says which commit, and reads as a sentence |
 | `authorize_unredacted_request_evidence_access_with` | `access_control` | Long, and correct. It names exactly which access it authorizes |
-| `deliberately_store_request_evidence_unencrypted!(because:)` | `encryption: false` | Turning encryption off should be a sentence a reviewer can find in a diff, with the host's own reason attached — not a `false` |
+| `deliberately_store_request_evidence_unencrypted!` | `encryption: false` | Turning encryption off should be a sentence a reviewer can find in a diff — not a `false`. The method NAME is the ceremony; its `because:` is optional |
 
 The last row is the pattern worth copying. When an option has a consequence somebody should
 have to think about, make the name carry the thinking.

data/guides/request-evidence.md

@@ -310,7 +310,26 @@ Clickwrap.policy :regulated_authorization do
 end
 ```
 
-Every keyword there is doing work:
+Every keyword there is doing work, and **every one of them is optional**. The same three
+declarations with nothing at all supplied are valid, and record the same fields:
+
+```ruby
+Clickwrap.policy :frictionless_regulated_authorization do
+  authorize :regulated_action, one_time: true, valid_for: 10.minutes
+
+  record_ip_address
+  record_browser_user_agent
+  record_ip_geolocation
+  retain_with :regulated_evidence
+end
+```
+
+`record_ip_geolocation` with no field named records the coarse trio — country, region, city —
+and nothing finer. Name even one field and the set is exactly what you named; name every field
+`false` and Clickwrap refuses, because calling `record_ip_geolocation` and disabling everything
+cannot mean anything (`do_not_record_ip_geolocation` is how to say that).
+
+What each keyword adds when you do supply it:
 
 - **`because:`** is the present purpose, in a sentence someone outside engineering can read. It
   is stored and printed by `bin/rails clickwrap:privacy:inventory`. It is optional: a policy
@@ -319,7 +338,9 @@ Every keyword there is doing work:
   reviewed. What is refused is scaffolding text — `"TODO: ask legal"` is not a purpose.
 - **`legal_basis_reference:`** and **`data_protection_impact_assessment_reference:`** are
   host-supplied pointers to your own reviewed documents. Clickwrap stores them. It does not
-  read them, validate them, or endorse them.
+  read them, validate them, endorse them, or ever require them — nothing in the gem refuses a
+  recorded field for want of either, and nothing ever will. Your privacy policy owns the why;
+  the gem records the what.
 - **`delete_after:`** and **`retain_until:`** are both optional. When neither the policy, its
   retention class, nor the configuration names a schedule, the field keeps pace with the
   evidence it corroborates — the same posture the core event has — and the annex is stamped
@@ -554,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

@@ -1227,15 +1227,19 @@ module Clickwrap
       @keep_recorded_request_evidence_indefinitely[category.to_sym]
     end
 
-    def deliberately_store_request_evidence_unencrypted!(because:)
-      if because.to_s.strip.empty?
-        raise ConfigurationError,
-              "deliberately_store_request_evidence_unencrypted! needs a `because:` explaining " \
-              "the reviewed decision."
-      end
-
+    # The named escape hatch for turning encryption off. The ceremony is the
+    # method: you cannot reach `encrypt_recorded_* = false` without writing a
+    # line that says out loud what you are doing, and that line is what a
+    # reviewer finds in a diff. Since 0.3.1 the `because:` is optional — the
+    # gem records its own sentence when you do not write one — because the
+    # host's privacy policy owns the why, and demanding it twice never stopped
+    # anybody who had already typed this method name.
+    #
+    # Encryption itself is unchanged: on by default, for all three categories.
+    def deliberately_store_request_evidence_unencrypted!(because: nil)
       @deliberately_storing_request_evidence_unencrypted = true
-      @reason_for_storing_request_evidence_unencrypted = because
+      @reason_for_storing_request_evidence_unencrypted =
+        because.presence || Vocabulary::DEFAULT_REASON_FOR_STORING_REQUEST_EVIDENCE_UNENCRYPTED
     end
 
     def storing_request_evidence_unencrypted? = @deliberately_storing_request_evidence_unencrypted == true

data/lib/clickwrap/dsl/policy_builder.rb

@@ -239,24 +239,46 @@ module Clickwrap
         @request_evidence[:browser_user_agent] = RequestEvidencePolicy::NOT_RECORDED
       end
 
-      # Each IP-geolocation data field is named separately, because each one is
-      # a separate decision about what to keep about a person's network
+      # Each IP-geolocation data field can be named separately, because each one
+      # is a separate decision about what to keep about a person's network
       # context. `latitude_and_longitude` is one coupled choice: half a
       # coordinate is not a result. Whatever is enabled, the provider name,
       # source, estimated status, resolution time, and any accuracy or database
       # provenance the resolver supplies are stored with it automatically — a
       # policy cannot keep the coordinates and drop the uncertainty needed to
       # read them.
-      def record_ip_geolocation(country: false, region: false, city: false, postal_code: false,
-                                latitude_and_longitude: false, timezone: false, continent: false,
-                                metro_code: false, accuracy_radius_in_kilometers: false,
+      #
+      # Naming no field at all is the frictionless form:
+      #
+      #   record_ip_geolocation
+      #
+      # It records the same coarse trio as
+      # `config.record_request_evidence_by_default` — country, region, city —
+      # 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.
+      # 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,
                                 data_protection_impact_assessment_reference: nil,
                                 **unknown_options)
         refuse_unknown_options!("record_ip_geolocation", unknown_options)
-        @ip_geolocation_fields = {
+        named = {
           "country" => country,
           "region" => region,
           "city" => city,
@@ -267,6 +289,7 @@ module Clickwrap
           "metro_code" => metro_code,
           "accuracy_radius_in_kilometers" => accuracy_radius_in_kilometers
         }
+        @ip_geolocation_fields = default_ip_geolocation_fields_when_none_named(named)
         @ip_geolocation_resolver_name = using
 
         @request_evidence[:ip_geolocation] = RequestEvidencePolicy::Setting.new(
@@ -404,6 +427,34 @@ module Clickwrap
         end
       end
 
+      # 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)
+        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)]
+        end
+      end
+
       def resolved_ip_geolocation_fields(setting)
         return {} unless setting.record?
         return @ip_geolocation_fields if @request_evidence.key?(:ip_geolocation)

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,
@@ -241,8 +255,11 @@ module Clickwrap
 
       if ip_geolocation.record? && enabled.empty?
         raise DefinitionError,
-              "Policy #{policy_key} calls `record_ip_geolocation` but enables no field. " \
-              "Name the fields you actually need, for example `country: true`."
+              "Policy #{policy_key} calls `record_ip_geolocation` and then turns every field " \
+              "off, which cannot mean anything. Name the fields you want, for example " \
+              "`country: true`; call `record_ip_geolocation` with no fields at all for the " \
+              "coarse country, region, and city; or say `do_not_record_ip_geolocation` if that " \
+              "is what you meant."
       end
 
       if ip_geolocation.record? &&

data/lib/clickwrap/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Clickwrap
-  VERSION = "0.3.0"
+  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/clickwrap/vocabulary.rb

@@ -187,6 +187,15 @@ module Clickwrap
     DEFAULT_REASON_FOR_KEEPING_REQUEST_EVIDENCE_INDEFINITELY =
       "Corroboration lives as long as the evidence it corroborates"
 
+    # The reason recorded when a host turns off encryption for request evidence
+    # without writing their own. Calling the method is still the ceremony —
+    # `deliberately_store_request_evidence_unencrypted!` is a sentence a
+    # reviewer finds in a diff and cannot misread — but the gem no longer
+    # demands the sentence be phrased twice.
+    DEFAULT_REASON_FOR_STORING_REQUEST_EVIDENCE_UNENCRYPTED =
+      "The application deliberately stores request evidence unencrypted; the reason lives " \
+      "outside Clickwrap"
+
     # Provenance that travels with any stored IP-geolocation result. A policy
     # cannot keep provider-derived coordinates while stripping the uncertainty
     # needed to interpret them.

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
 
@@ -1160,23 +1163,30 @@ module Clickwrap
         validate_ip_geolocation_resolver_class_name!
       end
 
+      # A missing purpose and a missing deletion period are both fine, and the
+      # generated file simply omits those lines: the gem records its own stated
+      # purpose and keeps the field as long as the evidence it corroborates.
+      # Scaffolding text is the one thing still refused, because a `TODO` the
+      # installer writes into a shipped initializer is worse than no line at
+      # all — the gem would reject it at boot anyway.
       def validate_enabled_category!(label, enabled:, because:, delete_after_days:,
                                      reason_option:, retention_option:)
         return unless enabled
 
-        unless Clickwrap::ReviewedText.present_and_reviewed?(because)
+        if Clickwrap::ReviewedText.placeholder?(because)
           raise Thor::Error,
-                "Clickwrap cannot enable #{label} with a blank or scaffolding reason. " \
-                "Give the application's reviewed, present-tense reason with " \
-                "#{reason_option}=\"...\", or turn that category off. No files were written."
+                "Clickwrap cannot enable #{label} with a scaffolding reason " \
+                "(#{because.inspect}). Give the application's reviewed, present-tense reason " \
+                "with #{reason_option}=\"...\", or omit it entirely and let Clickwrap record " \
+                "its own stated purpose. No files were written."
         end
 
-        return if delete_after_days.positive?
+        return unless delete_after_days.negative?
 
         raise Thor::Error,
-              "Clickwrap cannot enable #{label} without a positive deletion period. " \
-              "Set #{retention_option}=DAYS to the period your application reviewed, or " \
-              "turn that category off. No files were written."
+              "#{retention_option} cannot be negative (got #{delete_after_days}). Give the " \
+              "number of days your application reviewed, or omit it and #{label} will keep " \
+              "pace with the evidence it corroborates. No files were written."
       end
 
       def validate_ip_geolocation_coordinates!

data/lib/generators/clickwrap/templates/initializer.rb.erb

@@ -287,19 +287,25 @@ Clickwrap.configure do |config|
   # event — the historical agreement, declaration, or authorization stays intact
   # and verifiable without it.
 
-<%- if record_ip_addresses? -%>
+<%- if record_ip_addresses? && reason_for_recording_ip_addresses.present? -%>
   config.reason_for_recording_ip_addresses_by_default =
     <%= reason_for_recording_ip_addresses.inspect %>
+<%- end -%>
+<%- if record_ip_addresses? && delete_recorded_ip_addresses_after_days.positive? -%>
   config.delete_recorded_ip_addresses_after = <%= delete_recorded_ip_addresses_after_days %>.days
 <%- end -%>
-<%- if record_browser_user_agents? -%>
+<%- if record_browser_user_agents? && reason_for_recording_browser_user_agents.present? -%>
   config.reason_for_recording_browser_user_agents_by_default =
     <%= reason_for_recording_browser_user_agents.inspect %>
+<%- end -%>
+<%- if record_browser_user_agents? && delete_recorded_browser_user_agents_after_days.positive? -%>
   config.delete_recorded_browser_user_agents_after = <%= delete_recorded_browser_user_agents_after_days %>.days
 <%- end -%>
-<%- if any_ip_geolocation_field? -%>
+<%- if any_ip_geolocation_field? && reason_for_recording_ip_geolocation.present? -%>
   config.reason_for_recording_ip_geolocation_by_default =
     <%= reason_for_recording_ip_geolocation.inspect %>
+<%- end -%>
+<%- if any_ip_geolocation_field? && delete_recorded_ip_geolocation_after_days.positive? -%>
   config.delete_recorded_ip_geolocation_after = <%= delete_recorded_ip_geolocation_after_days %>.days
 <%- end -%>
 <%- if records_any_request_evidence? -%>
@@ -332,8 +338,9 @@ Clickwrap.configure do |config|
   # Turning one of these off puts the raw value in plain text in your database,
   # and therefore in every ordinary backup and database dump. It is allowed,
   # because some applications have a reviewed reason, but it is never a quiet
-  # one-character change: Clickwrap refuses `false` until you have said why in
-  # `config.deliberately_store_request_evidence_unencrypted!(because: "…")`.
+  # one-character change: Clickwrap refuses `false` until you have written
+  # `config.deliberately_store_request_evidence_unencrypted!` above it. Writing
+  # that line IS the whole ceremony — its `because:` is optional.
   #
   # config.encrypt_recorded_ip_addresses = true
   # config.encrypt_recorded_browser_user_agents = true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickwrap
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - rameerez