clickwrap 0.2.1 → 0.3.1

data/guides/request-evidence.md

@@ -5,11 +5,25 @@ configured actor and authentication source, the policy and application version,
 request ID when one is available. None of that is derived from the person's network or browser.
 
 It records **nothing** about the request itself — no IP address, no browser user-agent, no
-IP-geolocation field — unless the initializer or a policy names that exact field. There is no
-category switch, no profile, and no option that turns one of these on as a side effect of
-turning on something else.
+IP-geolocation field — until the initializer or a policy says otherwise. Saying otherwise takes
+one line:
 
-That default is evidence design, not squeamishness. Three things follow from it:
+```ruby
+Clickwrap.configure do |config|
+  config.record_request_evidence_by_default = true
+end
+```
+
+That switch records exactly what its name says and nothing else: the IP address, the browser
+user agent, and a coarse country / region / city estimate. Every finer geolocation field — a
+postal code, coordinates, a timezone, a continent, a metro code, an accuracy radius — remains
+its own separately named line, and no option here turns a category on as a side effect of
+turning on something else. There is still no profile switch and no name that hides its
+contents (`gdpr_compliant_mode`, `maximum_evidence`, `legal_proof`); a switch that reads
+`record_request_evidence_by_default` is the opposite of one.
+
+The gem's own default is still record-nothing, and that default is evidence design, not
+squeamishness. Three things follow from it:
 
 - An IP address and other online identifiers can be personal data. The CJEU addressed dynamic
   IP addresses in [Breyer, Case C-582/14](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A62014CJ0582)
@@ -230,7 +244,8 @@ they tell an auditor completely different things:
 
 Two places, and the policy always wins.
 
-**In the initializer, for every policy.** Each field is its own setting, and each is `false`:
+**In the initializer, for every policy.** Either the one switch, or the individual settings —
+each field has its own, and each is `false`:
 
 ```ruby
 Clickwrap.configure do |config|
@@ -242,10 +257,15 @@ Clickwrap.configure do |config|
 end
 ```
 
-Turning a default on without a purpose or without a deletion period is a `ConfigurationError`
-at the end of the `configure` block, not a warning. Enabling any
-`record_ip_geolocation_*_by_default` without an `ip_geolocation_resolver` is likewise a
-`ConfigurationError` — there would be nothing to resolve them.
+Everything below the first line there is optional. A purpose you do not write becomes
+Clickwrap's own stated one (marked `gem_default` in the inventory); a deletion period you do
+not set means the field keeps pace with the evidence it corroborates.
+
+Three things are still a `ConfigurationError` at the end of the `configure` block rather than a
+warning: scaffolding text standing in for a purpose, a deletion clock set alongside
+`keep_recorded_..._indefinitely!` for the same category, and enabling a
+`record_ip_geolocation_*_by_default` field with no `ip_geolocation_resolver` configured *and*
+no `trackdown` in the bundle — there would be nothing to resolve them with.
 
 **In one policy, for one flow.** This is the shape most applications want: ordinary signup
 inherits nothing, and the one consequential action opts in by name.
@@ -290,16 +310,43 @@ Clickwrap.policy :regulated_authorization do
 end
 ```
 
-Every keyword there is doing work:
+Every keyword there is doing work, and **every one of them is optional**. The same three
+declarations with nothing at all supplied are valid, and record the same fields:
+
+```ruby
+Clickwrap.policy :frictionless_regulated_authorization do
+  authorize :regulated_action, one_time: true, valid_for: 10.minutes
+
+  record_ip_address
+  record_browser_user_agent
+  record_ip_geolocation
+  retain_with :regulated_evidence
+end
+```
+
+`record_ip_geolocation` with no field named records the coarse trio — country, region, city —
+and nothing finer. Name even one field and the set is exactly what you named; name every field
+`false` and Clickwrap refuses, because calling `record_ip_geolocation` and disabling everything
+cannot mean anything (`do_not_record_ip_geolocation` is how to say that).
+
+What each keyword adds when you do supply it:
 
 - **`because:`** is the present purpose, in a sentence someone outside engineering can read. It
-  is stored, printed by `bin/rails clickwrap:privacy:inventory`, and required.
+  is stored and printed by `bin/rails clickwrap:privacy:inventory`. It is optional: a policy
+  that omits it records Clickwrap's own stated purpose instead, and the inventory marks that
+  entry `"purpose_source": "gem_default"` so nobody mistakes it for a sentence your team
+  reviewed. What is refused is scaffolding text — `"TODO: ask legal"` is not a purpose.
 - **`legal_basis_reference:`** and **`data_protection_impact_assessment_reference:`** are
   host-supplied pointers to your own reviewed documents. Clickwrap stores them. It does not
-  read them, validate them, or endorse them.
-- **`delete_after:`** or **`retain_until:`** is not optional. If a policy records a field and
-  neither the policy nor the configuration says when it goes away, capture raises a
-  `ConfigurationError` before the row is written. There is no keep-forever default in this gem.
+  read them, validate them, endorse them, or ever require them — nothing in the gem refuses a
+  recorded field for want of either, and nothing ever will. Your privacy policy owns the why;
+  the gem records the what.
+- **`delete_after:`** and **`retain_until:`** are both optional. When neither the policy, its
+  retention class, nor the configuration names a schedule, the field keeps pace with the
+  evidence it corroborates — the same posture the core event has — and the annex is stamped
+  with no deadline at all, so the retention planner never lists it. Setting a clock alongside
+  an application-wide `keep_recorded_..._indefinitely!` for the same category is still refused:
+  those are opposite decisions.
 - **`fail_if_unavailable:`** (default `false`) decides whether evidence you cannot get is worse
   than no capture at all. When it is `true` and the field cannot be resolved, the capture and
   the protected action roll back together.
@@ -359,6 +406,12 @@ So "we record IP addresses" is not one decision. It is four:
    later reader identify which rules were in force — the difference between corroborating
    evidence and a number with no recorded collection context.
 
+   Since 0.3.0 this step is not a precondition for recording an address. Leave it unset and the
+   annex stores `trusted_proxy_configuration_digest` as `nil`, which is the honest reading of
+   the situation: nobody recorded having reviewed a proxy topology when this address was
+   observed. `bin/rails clickwrap:doctor` warns while it stays that way. Hosts who complete
+   step 4 get the stronger record; hosts who do not get an address that says what it is worth.
+
 If you replace the reader, you own that decision, and the receipt says so: any host-assigned
 lambda is labeled `host_configured_reader` rather than `rails_request_remote_ip`, even when the
 body is identical. Clickwrap will not claim Rails' spoof checks on your behalf.
@@ -378,6 +431,18 @@ gem and must never become one.
 bundle add trackdown --version ">= 0.4"
 ```
 
+That is the whole wiring step. When your bundle carries trackdown and you have not named a
+resolver of your own, Clickwrap uses `Clickwrap::IpGeolocation::TrackdownResolver` for any
+policy that records IP geolocation — lazily, only at the moment something actually needs an
+address resolved, and never as a collection decision on its own (nothing is resolved until a
+policy has already enabled a geolocation field). `bin/rails clickwrap:privacy:inventory` reports
+that resolver with `"source": "gem_default"`, and `clickwrap:doctor` names it, so an adopted
+resolver never reads as a host decision. An installed trackdown older than 0.4 is not hidden
+behind "the gem is missing": you get the adapter's own sentence about upgrading.
+
+Set it explicitly when you want a different provider per policy, or when you are wiring
+Trackdown's per-request CDN trust:
+
 ```ruby
 # clickwrap-doc-test: syntax-only — requires the optional trackdown gem installed above
 Trackdown.configure do |trackdown|

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

data/lib/clickwrap/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/policy_builder.rb

@@ -239,24 +239,34 @@ module Clickwrap
         @request_evidence[:browser_user_agent] = RequestEvidencePolicy::NOT_RECORDED
       end
 
-      # Each IP-geolocation data field is named separately, because each one is
-      # a separate decision about what to keep about a person's network
+      # Each IP-geolocation data field can be named separately, because each one
+      # is a separate decision about what to keep about a person's network
       # context. `latitude_and_longitude` is one coupled choice: half a
       # coordinate is not a result. Whatever is enabled, the provider name,
       # source, estimated status, resolution time, and any accuracy or database
       # provenance the resolver supplies are stored with it automatically — a
       # policy cannot keep the coordinates and drop the uncertainty needed to
       # read them.
-      def record_ip_geolocation(country: false, region: false, city: false, postal_code: false,
-                                latitude_and_longitude: false, timezone: false, continent: false,
-                                metro_code: false, accuracy_radius_in_kilometers: false,
+      #
+      # Naming no field at all is the frictionless form:
+      #
+      #   record_ip_geolocation
+      #
+      # It records the same coarse trio as
+      # `config.record_request_evidence_by_default` — country, region, city —
+      # and nothing finer, because that is what "IP geolocation" means in this
+      # gem when nobody narrows it. Naming even one field means you are
+      # choosing the set yourself, and then the set is exactly what you named.
+      def record_ip_geolocation(country: nil, region: nil, city: nil, postal_code: nil,
+                                latitude_and_longitude: nil, timezone: nil, continent: nil,
+                                metro_code: nil, accuracy_radius_in_kilometers: nil,
                                 using: nil, encrypted: nil, delete_after: nil, retain_until: nil,
                                 fail_if_unavailable: false, because: nil,
                                 legal_basis_reference: nil,
                                 data_protection_impact_assessment_reference: nil,
                                 **unknown_options)
         refuse_unknown_options!("record_ip_geolocation", unknown_options)
-        @ip_geolocation_fields = {
+        named = {
           "country" => country,
           "region" => region,
           "city" => city,
@@ -267,6 +277,7 @@ module Clickwrap
           "metro_code" => metro_code,
           "accuracy_radius_in_kilometers" => accuracy_radius_in_kilometers
         }
+        @ip_geolocation_fields = default_ip_geolocation_fields_when_none_named(named)
         @ip_geolocation_resolver_name = using
 
         @request_evidence[:ip_geolocation] = RequestEvidencePolicy::Setting.new(
@@ -404,6 +415,20 @@ module Clickwrap
         end
       end
 
+      # `nil` means "the policy did not mention this field"; `false` means "the
+      # policy named it and turned it off". The distinction is the whole reason
+      # the keywords default to nil: a policy that mentions nothing gets the
+      # coarse trio, and a policy that explicitly sets every field to false
+      # still reaches the coherence check that tells it to say
+      # `do_not_record_ip_geolocation` instead.
+      def default_ip_geolocation_fields_when_none_named(named)
+        return named.transform_values { |value| value == true } if named.any? { |_, value| !value.nil? }
+
+        Vocabulary::IP_GEOLOCATION_DATA_FIELDS.to_h do |field|
+          [field, Vocabulary::COARSE_IP_GEOLOCATION_DATA_FIELDS.include?(field)]
+        end
+      end
+
       def resolved_ip_geolocation_fields(setting)
         return {} unless setting.record?
         return @ip_geolocation_fields if @request_evidence.key?(:ip_geolocation)

data/lib/clickwrap/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.