clickwrap 0.2.1 → 0.3.1

data/lib/clickwrap/privacy.rb

@@ -125,7 +125,7 @@ module Clickwrap
           "browser_user_agent" => default_category(config, :browser_user_agent),
           "ip_geolocation" => default_category(config, :ip_geolocation).merge(
             "fields" => config.enabled_default_ip_geolocation_fields,
-            "resolver" => describe_resolver(config.ip_geolocation_resolver),
+            "resolver" => describe_resolver(config),
             "fail_capture_when_unavailable" => config.fail_capture_when_ip_geolocation_is_unavailable
           ),
           "review_default_request_evidence_configuration_on" =>
@@ -138,14 +138,25 @@ module Clickwrap
         }
       end
 
+      # `because` is the purpose that will actually be recorded, and
+      # `purpose_source` says who wrote it. A `"gem_default"` purpose is a real
+      # purpose and it is stored with the evidence — but nobody should mistake
+      # Clickwrap's own sentence for one the host's team reviewed, so the
+      # inventory never lets the two look alike.
       def default_category(config, category)
+        recorded = default_recorded?(config, category)
+
         {
-          "recorded_by_default" => default_recorded?(config, category),
-          "because" => config.public_send(:"reason_for_recording_#{plural_for(category)}_by_default"),
+          "recorded_by_default" => recorded,
+          "because" => recorded ? config.reason_for_recording_by_default(category) : nil,
+          "purpose_source" => (config.reason_for_recording_by_default_source(category) if recorded),
           "legal_basis_reference" =>
             config.public_send(:"legal_basis_reference_for_recording_#{plural_for(category)}_by_default"),
           "encrypted" => config.public_send(:"encrypt_recorded_#{plural_for(category)}"),
-          "delete_after_seconds" => config.public_send(:"delete_recorded_#{plural_for(category)}_after")&.to_i
+          "delete_after_seconds" => config.public_send(:"delete_recorded_#{plural_for(category)}_after")&.to_i,
+          "kept_indefinitely" => config.keeps_recorded_request_evidence_indefinitely?(category),
+          "reason_for_keeping_indefinitely" =>
+            config.reason_for_keeping_recorded_request_evidence_indefinitely(category)
         }
       end
 
@@ -186,6 +197,7 @@ module Clickwrap
         entry = {
           "recorded" => setting.record?,
           "because" => setting.because,
+          "purpose_source" => policy.request_evidence.purpose_source_for(category),
           "legal_basis_reference" => setting.legal_basis_reference,
           "data_protection_impact_assessment_reference" =>
             setting.data_protection_impact_assessment_reference,
@@ -201,7 +213,7 @@ module Clickwrap
         entry.merge(
           "fields" => policy.request_evidence.enabled_ip_geolocation_fields,
           "resolver_named_by_policy" => policy.request_evidence.ip_geolocation_resolver_name&.to_s,
-          "resolver" => describe_resolver(Clickwrap.config.ip_geolocation_resolver)
+          "resolver" => describe_resolver(Clickwrap.config)
         )
       end
 
@@ -283,10 +295,19 @@ module Clickwrap
         }
       end
 
-      def describe_resolver(resolver)
+      # Reports the resolver in force, and whether the host named it or
+      # Clickwrap adopted the official trackdown adapter because their bundle
+      # already carried it. Asking never causes that adoption to happen — an
+      # inventory describes a configuration, it does not make one.
+      def describe_resolver(config)
+        resolver = config.ip_geolocation_resolver_in_force
         return { "configured" => false } if resolver.nil?
 
-        { "configured" => true, "class" => resolver.class.name }
+        {
+          "configured" => true,
+          "class" => resolver.class.name,
+          "source" => config.ip_geolocation_resolver_was_adopted_automatically? ? "gem_default" : "host"
+        }
       end
 
       def plural_for(category)

data/lib/clickwrap/request_evidence_extractor.rb

@@ -244,7 +244,10 @@ module Clickwrap
 
       # Provenance is recorded even when the value is not, because "which reader
       # was asked, under which reviewed proxy configuration" is what tells a
-      # later reader how much the address is worth.
+      # later reader how much the address is worth. A nil digest is part of
+      # that answer rather than a hole in it: it says no reviewed proxy
+      # configuration was recorded when this address was observed, which is
+      # exactly what a reader should know about it.
       provenance = {
         ip_address_reader_name: ip_address_reader_name,
         trusted_proxy_configuration_digest: policy.trusted_proxy_configuration_digest
@@ -484,13 +487,17 @@ module Clickwrap
     # --- Retention ------------------------------------------------------------
 
     # Every recorded field leaves here with a disposal answer: a date, the name
-    # of a host rule that will produce one, or the explicit reviewed decision
-    # to keep it as long as the evidence it corroborates. Keeping forever is
-    # never a silent default — it is a named declaration in the retention class
-    # (`keep_recorded_..._indefinitely`) or the initializer
-    # (`keep_recorded_..._indefinitely!(because: "…")`) — and a recorded field
-    # with no answer at all is a configuration bug caught before the row is
-    # written rather than a row nobody ever decided about.
+    # of a host rule that will produce one, or no schedule at all — which means
+    # it keeps pace with the evidence it corroborates, exactly like an
+    # indefinite core event. A blank schedule is the answer, not a gap: the
+    # planner never lists these rows, and the receipt reports them as recorded
+    # rather than as anything pending.
+    #
+    # Until 0.3.0 this raised when nothing had named a schedule, on the theory
+    # that keeping forever must never be silent. The theory held; the cost did
+    # not. It refused captures for hosts who had simply not written a sentence,
+    # and pushed integrators toward recording nothing — which is worse evidence
+    # than evidence kept under the same posture as the agreement it belongs to.
     #
     # `retain_until` names a host calculation instead of a duration because real
     # record-keeping schedules are not always durations — "five years, or three
@@ -504,15 +511,7 @@ module Clickwrap
       return { "#{category}_delete_after": now + class_rule.duration } if class_rule&.duration?
       return { "#{category}_retain_until_rule": class_rule.host_event_name.to_s } if class_rule&.host_event?
 
-      # Indefinite — declared in the class or application-wide — stamps
-      # nothing: the blank schedule plus the recorded declaration IS the
-      # disposal answer, exactly like an indefinite core event.
-      if class_rule&.indefinite? ||
-         Clickwrap.config.keeps_recorded_request_evidence_indefinitely?(category)
-        return {}
-      end
-
-      raise ConfigurationError, missing_retention_message(category)
+      {}
     end
 
     def retention_class_rule_for(category)
@@ -521,16 +520,6 @@ module Clickwrap
       Clickwrap.retention_class!(policy.retention_class_key).rule_for(category)
     end
 
-    def missing_retention_message(category)
-      "Clickwrap is about to record #{category} for policy #{policy_key} and nothing says what " \
-        "should ever happen to it. Give the policy a rule — `delete_after:` with a reviewed " \
-        "period, or `retain_until:` naming a host retention calculation — add a #{category} " \
-        "rule (or `keep_recorded_#{category}_indefinitely`) to retention class " \
-        "#{policy.retention_class_key.inspect}, or answer it application-wide with " \
-        "`keep_recorded_..._indefinitely!(because: \"…\")`. Keeping forever is never silent, " \
-        "and Clickwrap will not choose for you."
-    end
-
     # --- Failing closed -------------------------------------------------------
 
     # A policy can decide that evidence it cannot get is worse than no capture

data/lib/clickwrap/request_evidence_policy.rb

@@ -8,9 +8,15 @@ module Clickwrap
   # not squeamishness about useful data: it is that high-quality evidence is
   # purpose-specific. An IP address is personal data, and keeping it on your own
   # infrastructure does not remove the duty to have a reason for it, protect it,
-  # and stop keeping it eventually. So each field is enabled by name, with a
-  # plain-English purpose and a retention decision attached, and the policy that
-  # enables it is the server's, never the browser's.
+  # and stop keeping it eventually. So each field is enabled by name, and the
+  # policy that enables it is the server's, never the browser's.
+  #
+  # Naming a field is the whole requirement. Every recorded category still
+  # leaves here carrying a purpose and a disposal posture, because a snapshot
+  # read years from now has to answer both questions — but since 0.3.0 those
+  # answers have honest gem-supplied defaults instead of being the entry fee. A
+  # host who writes their own keeps their own words, and the privacy inventory
+  # reports which of the two is looking back at you.
   #
   # None of these fields is identity or physical location. An IP address is a
   # network observation. IP geolocation is a provider's estimate about that
@@ -61,9 +67,11 @@ module Clickwrap
                    trusted_proxy_configuration_digest: nil, review_configuration_on: nil)
       @policy_key = policy_key
       @retention_class_key = retention_class_key&.to_s
+      @purpose_sources = {}
       @ip_address = normalized_setting(:ip_address, ip_address || NOT_RECORDED)
       @browser_user_agent = normalized_setting(:browser_user_agent, browser_user_agent || NOT_RECORDED)
       @ip_geolocation = normalized_setting(:ip_geolocation, ip_geolocation || NOT_RECORDED)
+      @purpose_sources.freeze
       @ip_geolocation_fields = normalize_geolocation_fields(ip_geolocation_fields)
       @ip_geolocation_resolver_name = ip_geolocation_resolver_name&.to_sym
       @trusted_proxy_configuration_digest = trusted_proxy_configuration_digest&.to_s
@@ -87,6 +95,15 @@ module Clickwrap
 
     def records_anything? = records_ip_address? || records_browser_user_agent? || records_ip_geolocation?
 
+    # Who wrote the purpose stored for this category: `"host"` when the policy
+    # or the initializer supplied one, `"gem_default"` when Clickwrap filled in
+    # its own. Deliberately kept off `to_snapshot`: the snapshot is a released
+    # evidence format, and the answer is derivable from the configuration a
+    # reader already has.
+    def purpose_source_for(category)
+      @purpose_sources[category.to_s]
+    end
+
     def setting_for(category)
       case category.to_sym
       when :ip_address then ip_address
@@ -132,7 +149,6 @@ module Clickwrap
       FIELD_CATEGORIES.each { |category| validate_category!(category) }
       validate_geolocation_coherence!
       validate_named_resolver!
-      validate_trusted_proxy_configuration_digest!
     end
 
     def normalized_setting(category, setting)
@@ -153,7 +169,16 @@ module Clickwrap
               "`config.encrypt_recorded_*` setting, or omit `encrypted:` to inherit it."
       end
 
-      Setting.new(**setting.to_h, encrypted: configured)
+      # The compiled revision always carries a purpose, so a reader years from
+      # now never finds a recorded field with nothing beside it saying what it
+      # was for. Whose sentence it is gets remembered separately.
+      @purpose_sources[category.to_s] = setting.because.presence ? "host" : "gem_default"
+
+      Setting.new(
+        **setting.to_h,
+        encrypted: configured,
+        because: setting.because.presence || Vocabulary::DEFAULT_REQUEST_EVIDENCE_PURPOSE
+      )
     end
 
     def validate_named_resolver!
@@ -164,8 +189,9 @@ module Clickwrap
         raise DefinitionError,
               "Policy #{policy_key} records IP geolocation using resolver " \
               "#{ip_geolocation_resolver_name.inspect}, but no resolver is registered under " \
-              "that name. Configure `config.ip_geolocation_resolver` for " \
-              "`:application_default`, or register the named resolver with " \
+              "that name. Bundle `trackdown` (>= 0.4) and Clickwrap uses it for " \
+              "`:application_default` with no wiring line at all, or set " \
+              "`config.ip_geolocation_resolver` yourself, or register the named resolver with " \
               "`config.register_ip_geolocation_resolver`. Registered resolvers: " \
               "#{Clickwrap.config.ip_geolocation_resolver_names.join(", ").presence || "(none)"}."
       end
@@ -186,34 +212,21 @@ module Clickwrap
             "capabilities: #{error.message}"
     end
 
+    # A missing purpose and a missing disposal answer both have defaults now.
+    # What is left refuses only the two things a default cannot honestly stand
+    # in for: scaffolding text the host actually wrote, and a deletion clock
+    # that is not a period.
     def validate_category!(category)
       setting = setting_for(category)
       return unless setting.record?
 
-      if setting.because.to_s.strip.empty?
-        raise DefinitionError,
-              "Policy #{policy_key} records #{category} but gives no `because:`. Say in one " \
-              "plain sentence why this policy needs it right now. \"We might need it someday\" " \
-              "is not a purpose, and a privacy notice mentioning the field is not one either."
-      end
-
       if ReviewedText.placeholder?(setting.because)
         raise DefinitionError,
               "Policy #{policy_key} records #{category}, but its `because:` is still " \
               "scaffolding text (#{setting.because.inspect}). Replace it with the " \
-              "application's reviewed, present-tense reason; Clickwrap never treats a TODO " \
-              "as a data-collection purpose."
-      end
-
-      if setting.delete_after.nil? && setting.retain_until.nil? && retention_class_key.nil? &&
-         !Clickwrap.config.keeps_recorded_request_evidence_indefinitely?(category)
-        raise DefinitionError,
-              "Policy #{policy_key} records #{category} but nothing says what should ever " \
-              "happen to it. Give it `delete_after:` with a duration, or `retain_until:` " \
-              "naming a host event rule, attach a retention class with a rule for this " \
-              "category, or answer it application-wide with " \
-              "`keep_recorded_..._indefinitely!(because: \"…\")`. Keeping forever is never " \
-              "silent, and Clickwrap will not choose for you."
+              "application's reviewed, present-tense reason, or drop the option and let " \
+              "Clickwrap record its own stated purpose; a TODO is never a data-collection " \
+              "purpose."
       end
 
       return unless setting.delete_after && setting.delete_after.to_i <= 0
@@ -228,8 +241,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? &&
@@ -248,17 +264,5 @@ module Clickwrap
             "Policy #{policy_key} enables the IP-geolocation fields #{enabled.join(", ")} " \
             "without recording IP geolocation."
     end
-
-    def validate_trusted_proxy_configuration_digest!
-      return unless records_ip_address? || records_ip_geolocation?
-      return unless trusted_proxy_configuration_digest.to_s.strip.empty?
-
-      raise DefinitionError,
-            "Policy #{policy_key} records an IP address or derives IP geolocation, but " \
-            "`config.trusted_proxy_configuration_digest` is blank. Review the deployment's " \
-            "trusted-proxy topology, digest that reviewed configuration, and set the prefixed " \
-            "digest (for example `sha256:...`). This records which proxy decision produced the " \
-            "address; it does not claim that the decision was correct."
-    end
   end
 end

data/lib/clickwrap/services/validate_policy_references.rb

@@ -15,7 +15,6 @@ module Clickwrap
         Clickwrap.policies.each do |policy|
           validate_documents!(policy)
           retention_class = validate_retention_class!(policy)
-          validate_request_evidence_retention!(policy, retention_class)
           validate_host_calculations!(policy, retention_class)
           validate_authority_adapter!(policy)
           validate_ip_geolocation_resolver!(policy)
@@ -105,37 +104,13 @@ module Clickwrap
           )
       end
 
-      def validate_request_evidence_retention!(policy, retention_class)
-        RequestEvidencePolicy::FIELD_CATEGORIES.each do |category|
-          setting = policy.request_evidence.setting_for(category)
-          next unless setting.record?
-          next if setting.delete_after || setting.retain_until || retention_class.rule_for(category)
-          # The application-wide answer counts too: recording enabled in the
-          # initializer carries its disposal decision in the same place —
-          # either a global clock or the explicit, reasoned keep-indefinitely.
-          next if config_answers_disposal_for?(category)
-
-          raise DefinitionError,
-                "Policy #{policy.key} records #{category}, but nothing says when to dispose of " \
-                "it. Add `delete_after:`/`retain_until:` to the policy, a plain-English " \
-                "request-evidence rule (or `keep_recorded_#{category}_indefinitely`) to " \
-                "retention class #{retention_class.key}, or answer it application-wide in the " \
-                "initializer with `delete_recorded_..._after` or " \
-                "`keep_recorded_..._indefinitely!(because: \"…\")`."
-        end
-      end
-
-      def config_answers_disposal_for?(category)
-        clock =
-          case category.to_sym
-          when :ip_address then Clickwrap.config.delete_recorded_ip_addresses_after
-          when :browser_user_agent then Clickwrap.config.delete_recorded_browser_user_agents_after
-          else Clickwrap.config.delete_recorded_ip_geolocation_after
-          end
-
-        clock.present? || Clickwrap.config.keeps_recorded_request_evidence_indefinitely?(category)
-      end
-
+      # There is deliberately no disposal check here any more. A recorded
+      # category with no clock anywhere — not on the policy, not in its
+      # retention class, not in the initializer — means it keeps pace with the
+      # evidence it corroborates, which is what the core event does by default
+      # too. What still fails below is a rule that names a calculation nobody
+      # registered: a deadline waiting on a typo never arrives, and that is a
+      # different thing from a deliberate absence of one.
       def validate_host_calculations!(policy, retention_class)
         referenced = retention_class.rules.values.filter_map do |rule|
           rule.host_event_name&.to_sym

data/lib/clickwrap/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Clickwrap
-  VERSION = "0.2.1"
+  VERSION = "0.3.1"
 
   # 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

@@ -160,6 +160,42 @@ module Clickwrap
       accuracy_radius_in_kilometers
     ].freeze
 
+    # The three coarse fields `config.record_request_evidence_by_default = true`
+    # turns on. Coarse means administrative area, not a point: a country, a
+    # region, and a city are what a provider can estimate from an address with
+    # any confidence at all. Everything finer — a postal code, coordinates, a
+    # timezone, a metro code — stays its own separately named decision, because
+    # a switch that reads "record request evidence" should not hand somebody
+    # coordinates they never asked for.
+    COARSE_IP_GEOLOCATION_DATA_FIELDS = %w[country region city].freeze
+
+    # The purpose Clickwrap records when a host enables request evidence
+    # without writing a purpose of their own. It is the gem's own sentence, not
+    # a reviewed host decision, and the privacy inventory says which of the two
+    # it is looking at. It exists because the alternative — refusing to boot
+    # until somebody writes a sentence — was pushing integrators to record
+    # nothing at all, and no corroboration is worse evidence than corroboration
+    # collected under the gem's stated purpose.
+    DEFAULT_REQUEST_EVIDENCE_PURPOSE =
+      "Corroborate who performed each recorded act, from where, on what client — to defend " \
+      "the recorded agreement itself."
+
+    # The reason recorded when a host keeps request evidence indefinitely
+    # without writing their own. Same posture as the purpose above: the
+    # declaration is still recorded and still readable years later; only the
+    # obligation to phrase it yourself is gone.
+    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

@@ -28,9 +28,13 @@ module Clickwrap
     # spelling of the off-by-default posture. It disappears after generation;
     # it is deliberately not a runtime concept. There is no
     # `record_network_context`, `record_everything`, `full_evidence`, or
-    # regulation-named mode switch anywhere in this gem, because a flag that
-    # enables a whole category of personal data is the thing this gem exists not
-    # to do, and no flag can make a legal determination on a host's behalf.
+    # regulation-named mode switch anywhere in this gem, because a flag whose
+    # name hides what it collects is the thing this gem exists not to ship, and
+    # no flag can make a legal determination on a host's behalf. The runtime's
+    # one grouped switch, `config.record_request_evidence_by_default`, is not
+    # one of those: it names its three fields and can never grow a fourth. The
+    # installer still asks about them one at a time, because a purpose the host
+    # wrote beats the honest default the gem would otherwise record.
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
@@ -1156,23 +1160,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

@@ -28,8 +28,11 @@
 #
 # There is deliberately no `maximum_evidence`, `full_evidence`, `legal_proof`,
 # or regulation-named mode setting. No runtime flag can make a legal
-# determination for you, and an option that turns on a category of personal data
-# as a side effect of something else is exactly what this gem exists not to do.
+# determination for you, and an option whose name does not say what it collects
+# is exactly what this gem exists not to ship. The one grouped switch that does
+# exist, `config.record_request_evidence_by_default`, names its own contents:
+# an IP address, a browser user agent, and a coarse country/region/city
+# estimate — nothing finer, ever.
 <%- if recipe -%>
 #
 # This file was scaffolded with `--request-evidence-recipe=<%= recipe %>`. The
@@ -251,10 +254,12 @@ Clickwrap.configure do |config|
   # proof that anyone was physically anywhere.
 <%- if records_any_request_evidence? -%>
   #
-  # You enabled some of these during install. The generator required an explicit
-  # purpose and deletion period before writing this file; review both below. The
-  # annex table itself came with `--with-request-evidence`, which this install
-  # added for you.
+  # You enabled some of these during install, and the installer asked for an
+  # explicit purpose and deletion period before writing this file; review both
+  # below. The gem itself would have accepted the fields without them and
+  # recorded its own stated purpose instead — the installer asks because a
+  # sentence your team wrote is worth more than one the gem supplied. The annex
+  # table came with `--with-request-evidence`, which this install added for you.
 <%- else -%>
   #
   # Everything here is off, which is the safe default — and the annex table was
@@ -272,26 +277,35 @@ Clickwrap.configure do |config|
 
   # --- Request evidence: why, how long, and how it is protected ---------------
   #
-  # An enabled field with a blank purpose or no deletion rule is a configuration
-  # error at boot, not a warning. "We turned it on and never decided why" is the
-  # failure mode these settings exist to prevent. There is no keep-forever
-  # default anywhere in this gem, and deleting a value removes the encrypted
-  # annex entry and appends a disposition event — the historical agreement,
-  # declaration, or authorization stays intact and verifiable without it.
-
-<%- if record_ip_addresses? -%>
+  # Both of these are optional, and the installer wrote yours because you gave
+  # them. A field enabled with no purpose records the one Clickwrap states, and
+  # the privacy inventory marks it as the gem's sentence rather than yours; a
+  # field with no deletion period keeps pace with the evidence it corroborates.
+  # What is refused is a purpose that is still scaffolding text, and a deletion
+  # period set alongside `keep_recorded_..._indefinitely!` for the same field.
+  # Deleting a value removes the encrypted annex entry and appends a disposition
+  # event — the historical agreement, declaration, or authorization stays intact
+  # and verifiable without it.
+
+<%- 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? -%>
@@ -301,10 +315,10 @@ Clickwrap.configure do |config|
   config.review_default_request_evidence_configuration_on = <%= review_date_literal %>
 <%- else -%>
   # Nothing above is enabled, so there is nothing to give a purpose or a
-  # deletion period to. Enabling a field is never one line — the gem refuses an
-  # enabled field with no recorded purpose and no deletion rule — and it wants a
-  # review date so the decision gets looked at again by a person instead of
-  # outliving its reason:
+  # deletion period to. Turning the ordinary three on later is one line —
+  # `config.record_request_evidence_by_default = true` — and these are the
+  # settings that upgrade it into a record your own team reviewed, plus a date
+  # so the decision gets looked at again instead of outliving its reason:
   #
   # config.reason_for_recording_ip_addresses_by_default = "Investigate disputed submissions"
   # config.delete_recorded_ip_addresses_after = 90.days
@@ -324,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
@@ -359,7 +374,9 @@ Clickwrap.configure do |config|
     Clickwrap.trusted_proxy_configuration_digest_for_rails_application
 <%- else -%>
   # A digest of the effective trusted-proxy rules, stored beside any recorded
-  # address. Nothing here records one, so there is nothing to stamp:
+  # address. Nothing here records one, so there is nothing to stamp. Set it if
+  # you enable IP recording later: it is not required, but without it every
+  # recorded address carries a blank where its collection context should be.
   #
   # config.trusted_proxy_configuration_digest =
   #   Clickwrap.trusted_proxy_configuration_digest_for_rails_application
@@ -368,8 +385,9 @@ Clickwrap.configure do |config|
 <%- if any_ip_geolocation_field? -%>
   # DECISION — you enabled IP-geolocation fields and explicitly selected this
   # resolver. Make its gem and data source available in every environment:
-  # Clickwrap refuses to boot with fields it has nothing to resolve, rather than
-  # recording blanks that later read as "no result".
+  # Clickwrap refuses to boot with fields nothing can resolve — no resolver here
+  # and no trackdown in the bundle — rather than recording blanks that later
+  # read as "no result".
   #
   # Only the fields authorized above are stored, never the whole result object,
   # and every stored value keeps the provider, source, estimated state,
@@ -378,11 +396,18 @@ Clickwrap.configure do |config|
   # needed to read them.
   config.ip_geolocation_resolver = <%= ip_geolocation_resolver_class_name %>.new
 <%- else -%>
-  # Required before any IP-geolocation field can be enabled, here or in a
-  # policy. The official optional resolver requires trackdown >= 0.4 so the
-  # provider that actually answered and per-request source trust are preserved:
+  # Something has to resolve an IP-geolocation field before it can be enabled,
+  # here or in a policy. Bundling trackdown is enough — Clickwrap uses the
+  # official adapter for you when you have not named a resolver of your own,
+  # and the privacy inventory reports it as the gem's choice rather than yours.
+  # It requires trackdown >= 0.4 so the provider that actually answered and
+  # per-request source trust are preserved:
   #
   #   bundle add trackdown --version ">= 0.4"
+  #
+  # Name it explicitly to pick a different provider, or when you are wiring
+  # Trackdown's per-request CDN trust:
+  #
   #   config.ip_geolocation_resolver = Clickwrap::IpGeolocation::TrackdownResolver.new
 <%- end -%>
 

metadata

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