clickwrap 0.2.1 → 0.3.0

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
@@ -248,17 +261,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.0"
 
   # 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,33 @@ 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"
+
     # 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
 

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,12 +277,15 @@ 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.
+  # 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? -%>
   config.reason_for_recording_ip_addresses_by_default =
@@ -301,10 +309,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
@@ -359,7 +367,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 +378,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 +389,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.0
 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