clickwrap 0.2.0 → 0.3.0

data/lib/clickwrap/configuration.rb

@@ -21,14 +21,18 @@ module Clickwrap
   #   - Every hook defaults to a no-op, so the gem works untouched and a host
   #     wires hooks only as needed.
   #   - Nothing here collects personal data by default. Every `record_*` flag
-  #     starts false, and turning one on without a purpose and a retention
-  #     decision is a configuration error, not a warning.
+  #     starts false. Turning one on takes one line and nothing else; the
+  #     purpose and the disposal answer have honest gem-supplied defaults, and
+  #     a host who wants reviewed ones writes them.
   #
   # One setting deserves its own note: there is deliberately no
   # `gdpr_compliant_mode`, `maximum_evidence`, `full_evidence`, or
-  # `legal_proof`. An option that silently enables a category of personal data
-  # is exactly the thing this gem exists not to do, and no runtime flag can
-  # make a legal determination on your behalf.
+  # `legal_proof`. Those names hide what they collect and pretend to make a
+  # legal determination, which is exactly the thing this gem exists not to do.
+  # `record_request_evidence_by_default` is the opposite kind of switch: it
+  # says out loud what it records (an IP address, a browser user agent, and a
+  # coarse country/region/city estimate), it enables nothing finer, and it
+  # claims nothing about the law.
   class Configuration
     DOCUMENT_STORES = %i[database active_storage resolver].freeze
     DIGEST_ALGORITHMS = %i[sha256 sha384 sha512].freeze
@@ -228,10 +232,14 @@ module Clickwrap
       @encrypt_recorded_ip_geolocation = true
 
       # nil means "every policy that enables the field must supply its own
-      # rule". There is no keep-forever default anywhere in this gem.
+      # rule" — or, for by-default recording, that the host has said
+      # `keep_recorded_..._indefinitely!(because: "…")` out loud. Keeping
+      # forever is never silent: it is either the per-policy retention class's
+      # explicit business, or a named, reasoned sentence in the initializer.
       @delete_recorded_ip_addresses_after = nil
       @delete_recorded_browser_user_agents_after = nil
       @delete_recorded_ip_geolocation_after = nil
+      @keep_recorded_request_evidence_indefinitely = {}
 
       # Rails' request.remote_ip is the conventional reader. The host remains
       # responsible for configuring and testing trusted proxies correctly:
@@ -242,6 +250,8 @@ module Clickwrap
 
       @ip_geolocation_resolver = nil
       @ip_geolocation_resolvers = {}
+      @automatically_adopted_ip_geolocation_resolver = nil
+      @considered_automatic_ip_geolocation_resolver = false
       @fail_capture_when_ip_geolocation_is_unavailable = false
 
       # The keyed annex digest carries a key ID so a host can rotate keys
@@ -608,6 +618,49 @@ module Clickwrap
 
     # --- Request-evidence setters --------------------------------------------
 
+    # The one switch.
+    #
+    #   config.record_request_evidence_by_default = true
+    #
+    # 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. Nothing finer — a postal code, coordinates, a timezone, a
+    # metro code — and nothing else at all. The purpose and the disposal answer
+    # have honest gem defaults (see `Vocabulary::DEFAULT_REQUEST_EVIDENCE_PURPOSE`
+    # and the keep-indefinitely posture below), so this line is genuinely the
+    # whole first step.
+    #
+    # It is a fan-out setter, not a mode: it writes the individual
+    # `record_*_by_default` flags, which means it composes with them in reading
+    # order. Write the switch first and a narrower flag after it to carve one
+    # field back out —
+    #
+    #   config.record_request_evidence_by_default = true
+    #   config.record_browser_user_agent_by_default = false
+    #
+    # — and any policy can still override all of it with `record_ip_address`,
+    # `do_not_record_ip_address`, and their siblings. Setting it to false turns
+    # the same three fields off and leaves the finer geolocation fields alone,
+    # because it never turned those on.
+    def record_request_evidence_by_default=(value)
+      enabled = ensure_boolean(value, "record_request_evidence_by_default")
+
+      @record_ip_address_by_default = enabled
+      @record_browser_user_agent_by_default = enabled
+      Vocabulary::COARSE_IP_GEOLOCATION_DATA_FIELDS.each do |field|
+        instance_variable_set(:"@record_ip_geolocation_#{field}_by_default", enabled)
+      end
+    end
+
+    # Reads back what the switch describes rather than a remembered assignment:
+    # true when all three coarse fields are on, however they were turned on.
+    def record_request_evidence_by_default
+      record_ip_address_by_default && record_browser_user_agent_by_default &&
+        Vocabulary::COARSE_IP_GEOLOCATION_DATA_FIELDS.all? do |field|
+          public_send(:"record_ip_geolocation_#{field}_by_default")
+        end
+    end
+
     def record_ip_address_by_default=(value)
       @record_ip_address_by_default = ensure_boolean(value, "record_ip_address_by_default")
     end
@@ -711,11 +764,36 @@ module Clickwrap
     end
 
     def ip_geolocation_resolver_for(name = nil)
-      return ip_geolocation_resolver if name.blank? || name.to_s == "application_default"
+      return application_default_ip_geolocation_resolver if name.blank? || name.to_s == "application_default"
 
       @ip_geolocation_resolvers[name.to_s]
     end
 
+    # What a policy gets when it does not name a resolver: the host's own, or —
+    # when they never set one and their bundle already carries `trackdown` 0.4
+    # or newer — the official adapter for it. That is the whole "trackdown plus
+    # Cloudflare just works" path, and it is deliberately not a silent
+    # collection decision: nothing calls this until a policy has already
+    # enabled an IP-geolocation field.
+    #
+    # An installed-but-too-old trackdown is NOT hidden here. The adapter's own
+    # sentence about upgrading is more useful than pretending the gem is
+    # missing.
+    def application_default_ip_geolocation_resolver
+      @ip_geolocation_resolver || automatically_adopted_ip_geolocation_resolver
+    end
+
+    # The resolver actually in force, for anything that only wants to describe
+    # the configuration (the privacy inventory, `clickwrap:doctor`). Unlike the
+    # reader above it never adopts one as a side effect of being asked.
+    def ip_geolocation_resolver_in_force
+      @ip_geolocation_resolver || @automatically_adopted_ip_geolocation_resolver
+    end
+
+    def ip_geolocation_resolver_was_adopted_automatically?
+      @ip_geolocation_resolver.nil? && !@automatically_adopted_ip_geolocation_resolver.nil?
+    end
+
     def ip_geolocation_resolver_names = @ip_geolocation_resolvers.keys.sort.freeze
 
     # Plain-English key-rotation API. The ID is evidence and must stay stable;
@@ -838,7 +916,6 @@ module Clickwrap
     # caught the typos; these are the things that need the whole block resolved.
     def validate!
       validate_request_evidence_defaults!
-      validate_trusted_proxy_configuration!
       validate_ip_geolocation_resolver!
       true
     end
@@ -866,6 +943,15 @@ module Clickwrap
       Reference.record(actor)
     end
 
+    # Enabling a category by default needs nothing else. A purpose the host did
+    # not write falls back to Clickwrap's own stated one, and a disposal answer
+    # nobody gave means the corroboration keeps pace with the evidence it
+    # corroborates — which is what core evidence has done since 0.2.0.
+    #
+    # Two things still fail here, and both are the host contradicting
+    # themselves rather than merely leaving a blank: scaffolding text standing
+    # in for a purpose, and a deletion clock set alongside a declaration to
+    # keep the same category forever.
     def validate_request_evidence_defaults!
       {
         ip_address: [record_ip_address_by_default,
@@ -880,28 +966,20 @@ module Clickwrap
       }.each do |category, (enabled, reason, delete_after)|
         next unless enabled
 
-        if reason.to_s.strip.empty?
-          raise ConfigurationError,
-                "Clickwrap is set to record #{category} for every policy by default, but " \
-                "`reason_for_recording_#{plural_for(category)}_by_default` is blank. Say in one " \
-                "plain sentence why the application needs it. If only some policies need it, " \
-                "turn the default off and enable it in those policies instead."
-        end
-
         if ReviewedText.placeholder?(reason)
           raise ConfigurationError,
                 "Clickwrap is set to record #{category} for every policy by default, but its " \
                 "reason is still scaffolding text (#{reason.inspect}). Replace it with the " \
-                "application's reviewed, present-tense reason, or turn that default off."
+                "application's reviewed, present-tense reason, or delete the line and let " \
+                "Clickwrap record its own stated purpose."
         end
 
-        next unless delete_after.nil?
+        next unless delete_after.present? && keeps_recorded_request_evidence_indefinitely?(category)
 
         raise ConfigurationError,
-              "Clickwrap is set to record #{category} for every policy by default, but " \
-              "`delete_recorded_#{plural_for(category)}_after` is nil, so nothing would ever " \
-              "delete it. Set a reviewed period, or turn the default off and let each policy " \
-              "choose its own retention rule."
+              "Clickwrap is told both to delete recorded #{category} after " \
+              "#{delete_after.inspect} and to keep it indefinitely. Those are opposite " \
+              "decisions — keep exactly one."
       end
     end
 
@@ -913,31 +991,27 @@ module Clickwrap
       end
     end
 
-    def validate_trusted_proxy_configuration!
-      records_ip_derived_evidence =
-        record_ip_address_by_default || enabled_default_ip_geolocation_fields.any?
-      return unless records_ip_derived_evidence
-      return if trusted_proxy_configuration_digest.present?
+    def host_reason_for_recording_by_default(category)
+      public_send(:"reason_for_recording_#{plural_for(category.to_sym)}_by_default").presence
+    end
 
-      raise ConfigurationError,
-            "Clickwrap is set to record an IP address or derive IP geolocation for every " \
-            "policy, but `trusted_proxy_configuration_digest` is blank. Review and test the " \
-            "deployment's trusted-proxy topology, digest that exact configuration, and set " \
-            "the complete prefixed SHA-2 digest (for example `sha256:...`). This records which " \
-            "proxy decision produced the address; it does not claim that decision was correct."
+    def declare_indefinite_request_evidence!(category, because)
+      @keep_recorded_request_evidence_indefinitely[category] =
+        because.presence || Vocabulary::DEFAULT_REASON_FOR_KEEPING_REQUEST_EVIDENCE_INDEFINITELY
     end
 
     def validate_ip_geolocation_resolver!
-      return if ip_geolocation_resolver
       return if enabled_default_ip_geolocation_fields.empty? && !fail_capture_when_ip_geolocation_is_unavailable
+      return if application_default_ip_geolocation_resolver
 
       if enabled_default_ip_geolocation_fields.any?
         raise ConfigurationError,
               "Clickwrap is set to record the IP-geolocation fields " \
               "#{enabled_default_ip_geolocation_fields.join(", ")} but no " \
-              "`ip_geolocation_resolver` is configured, so there is nothing to resolve them. " \
-              "Set one (for example Clickwrap::IpGeolocation::TrackdownResolver.new) or turn " \
-              "the fields off."
+              "`ip_geolocation_resolver` is configured and the `trackdown` gem is not " \
+              "installed, so there is nothing to resolve them. Run " \
+              "`bundle add trackdown --version \">= 0.4\"` and Clickwrap will use it, set " \
+              "`config.ip_geolocation_resolver` to your own adapter, or turn the fields off."
       end
 
       raise ConfigurationError,
@@ -945,6 +1019,22 @@ module Clickwrap
             "`ip_geolocation_resolver` is configured, so every capture would fail."
     end
 
+    # Considered once, at the first moment something actually needs geolocation
+    # resolved, and remembered either way — including the "no trackdown here"
+    # answer, so a host without it does not pay for a failed `require` on every
+    # policy compile.
+    def automatically_adopted_ip_geolocation_resolver
+      return @automatically_adopted_ip_geolocation_resolver if @considered_automatic_ip_geolocation_resolver
+
+      # Remembered only once the adapter has actually been built. An installed
+      # trackdown too old to use raises out of here, and a host who fixes their
+      # bundle and asks again must not be told the gem is missing because a
+      # failed attempt got memoized as "no".
+      resolver = (IpGeolocation::TrackdownResolver.new if IpGeolocation::TrackdownResolver.installed?)
+      @considered_automatic_ip_geolocation_resolver = true
+      @automatically_adopted_ip_geolocation_resolver = resolver
+    end
+
     # --- Setter helpers -------------------------------------------------------
 
     def ensure_callable(value, name)
@@ -1095,9 +1185,48 @@ module Clickwrap
 
     public
 
-    # The deliberate, named escape hatch referenced by `ensure_encryption_choice`.
-    # It exists so that turning encryption off is a sentence a reviewer can find
-    # in a diff, with the host's own reason attached, rather than a `false`.
+    # Says out loud what an absent deletion clock already means: this category
+    # keeps pace with the evidence it corroborates. Request evidence exists to
+    # corroborate evidence that (since 0.2.0) keeps indefinitely by default,
+    # and a corroboration that expires before the thing it corroborates is a
+    # scheduled weakening of the record.
+    #
+    # Saying it explicitly is worth doing — it puts the decision and its reason
+    # in the initializer where a reviewer finds them — but since 0.3.0 it is no
+    # longer the price of admission, and `because:` is optional. What a host
+    # writes is kept as their own words; what they leave out gets Clickwrap's.
+    def keep_recorded_ip_addresses_indefinitely!(because: nil)
+      declare_indefinite_request_evidence!(:ip_address, because)
+    end
+
+    def keep_recorded_browser_user_agents_indefinitely!(because: nil)
+      declare_indefinite_request_evidence!(:browser_user_agent, because)
+    end
+
+    def keep_recorded_ip_geolocation_indefinitely!(because: nil)
+      declare_indefinite_request_evidence!(:ip_geolocation, because)
+    end
+
+    def keeps_recorded_request_evidence_indefinitely?(category)
+      @keep_recorded_request_evidence_indefinitely.key?(category.to_sym)
+    end
+
+    # The purpose that will actually be recorded for a category enabled
+    # application-wide, and which of the two wrote it. The inventory reports
+    # both, so a reviewer can tell a sentence their team signed off on from the
+    # one the gem supplied.
+    def reason_for_recording_by_default(category)
+      host_reason_for_recording_by_default(category) || Vocabulary::DEFAULT_REQUEST_EVIDENCE_PURPOSE
+    end
+
+    def reason_for_recording_by_default_source(category)
+      host_reason_for_recording_by_default(category) ? "host" : "gem_default"
+    end
+
+    def reason_for_keeping_recorded_request_evidence_indefinitely(category)
+      @keep_recorded_request_evidence_indefinitely[category.to_sym]
+    end
+
     def deliberately_store_request_evidence_unencrypted!(because:)
       if because.to_s.strip.empty?
         raise ConfigurationError,

data/lib/clickwrap/doctor.rb

@@ -271,7 +271,8 @@ module Clickwrap
     end
 
     def resolver_findings
-      configured = Clickwrap.config.ip_geolocation_resolver
+      config = Clickwrap.config
+      configured = config.ip_geolocation_resolver_in_force
       wanted = Clickwrap.policies.values.select { |policy| policy.request_evidence.records_ip_geolocation? }
 
       if configured.nil?
@@ -285,7 +286,11 @@ module Clickwrap
                         "as unavailable")]
       end
 
-      [ok("an IP-geolocation resolver is configured (#{configured.class.name})")]
+      return [ok("an IP-geolocation resolver is configured (#{configured.class.name})")] unless
+        config.ip_geolocation_resolver_was_adopted_automatically?
+
+      [ok("IP geolocation resolves through #{configured.class.name}, which Clickwrap adopted " \
+          "because this application bundles trackdown and named no resolver of its own")]
     end
 
     # An IP address read from a forwarded header is only as good as the proxy

data/lib/clickwrap/dsl/retention_builder.rb

@@ -69,6 +69,21 @@ module Clickwrap
         assign_rule!(:ip_geolocation, host_event_name:)
       end
 
+      # Keeping the annex as long as the core event it corroborates, said in
+      # the retention class itself. A corroboration that expires before the
+      # evidence it corroborates is a scheduled weakening of the record.
+      def keep_recorded_ip_address_indefinitely
+        assign_rule!(:ip_address, indefinite: true)
+      end
+
+      def keep_recorded_browser_user_agent_indefinitely
+        assign_rule!(:browser_user_agent, indefinite: true)
+      end
+
+      def keep_recorded_ip_geolocation_indefinitely
+        assign_rule!(:ip_geolocation, indefinite: true)
+      end
+
       def compile = RetentionClass.new(key: @key, rules: @rules)
 
       private

data/lib/clickwrap/ip_geolocation/trackdown_resolver.rb

@@ -83,6 +83,22 @@ module Clickwrap
 
       attr_reader :capabilities
 
+      # Whether the host's bundle carries `trackdown` at all. The configuration
+      # asks this before adopting the adapter for a policy that enabled
+      # IP-geolocation fields without naming a resolver, so the common case —
+      # trackdown plus Cloudflare, already bundled — needs no wiring line.
+      #
+      # It answers the narrow question it is named after and nothing else. An
+      # installed release older than 0.4 answers `true` here and then fails in
+      # the constructor with the sentence about upgrading, which is far more
+      # useful to that host than being told the gem is missing.
+      def self.installed?
+        require "trackdown" unless defined?(::Trackdown)
+        true
+      rescue ::LoadError
+        false
+      end
+
       # Trust is per request in Trackdown 0.4. A host registers its verifier with
       # Trackdown, Trackdown runs it against the same request that supplied the
       # CDN headers, and this adapter copies the result's explicit trust state.

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
@@ -483,10 +486,18 @@ module Clickwrap
 
     # --- Retention ------------------------------------------------------------
 
-    # Every recorded field leaves here with a disposal rule: a date, or the name
-    # of a host rule that will produce one. There is no keep-forever default
-    # anywhere in this gem, and a recorded field with neither is a configuration
-    # bug caught before the row is written rather than a row nobody ever deletes.
+    # Every recorded field leaves here with a disposal answer: a date, the name
+    # 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
@@ -500,7 +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?
 
-      raise ConfigurationError, missing_retention_message(category)
+      {}
     end
 
     def retention_class_rule_for(category)
@@ -509,14 +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 when " \
-        "to delete it. Give the policy a rule — `delete_after:` with a reviewed period, or " \
-        "`retain_until:` naming a host retention calculation — or add a #{category} rule to " \
-        "retention class #{policy.retention_class_key.inspect}. Clickwrap has no keep-forever " \
-        "default and will not choose a period 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,31 +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?
-        raise DefinitionError,
-              "Policy #{policy_key} records #{category} but never says when to delete it. " \
-              "Give it `delete_after:` with a duration, or `retain_until:` naming a host event " \
-              "rule, or attach a retention class with a rule for this category. Clickwrap has " \
-              "no keep-forever default."
+              "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
@@ -245,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