clickwrap 0.2.1 → 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
@@ -246,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
@@ -612,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
@@ -715,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;
@@ -842,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
@@ -870,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,
@@ -884,37 +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
 
-        if delete_after.present? && keeps_recorded_request_evidence_indefinitely?(category)
-          raise ConfigurationError,
-                "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
-
-        next if delete_after.present? || keeps_recorded_request_evidence_indefinitely?(category)
+        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 nothing " \
-              "says how long to keep it. Either set a reviewed period with " \
-              "`delete_recorded_#{plural_for(category)}_after`, or keep it as long as the " \
-              "evidence it corroborates with " \
-              "`keep_recorded_#{plural_for(category)}_indefinitely!(because: \"…\")` — 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
 
@@ -926,41 +991,27 @@ module Clickwrap
       end
     end
 
-    def declare_indefinite_request_evidence!(category, because)
-      if because.to_s.strip.empty?
-        raise ConfigurationError,
-              "keep_recorded_#{plural_for(category)}_indefinitely! needs a `because:` " \
-              "explaining the reviewed decision."
-      end
-
-      @keep_recorded_request_evidence_indefinitely[category] = because
+    def host_reason_for_recording_by_default(category)
+      public_send(:"reason_for_recording_#{plural_for(category.to_sym)}_by_default").presence
     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?
-
-      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,
@@ -968,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)
@@ -1118,24 +1185,25 @@ 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`.
-    # The named escape hatch for by-default request evidence with no deletion
-    # clock: 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. Same
-    # rule as every escape hatch here: keeping forever must be a sentence a
-    # reviewer can find in a diff, with the host's own reason attached.
-    def keep_recorded_ip_addresses_indefinitely!(because:)
+    # 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:)
+    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:)
+    def keep_recorded_ip_geolocation_indefinitely!(because: nil)
       declare_indefinite_request_evidence!(:ip_geolocation, because)
     end
 
@@ -1143,6 +1211,18 @@ module Clickwrap
       @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

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/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
@@ -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