clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/integrity/timestamp.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  module Integrity
+    # The adapter contract for a timestamp provider, plus a reference base
+    # implementation that issues no tokens and says so. Configuration defaults
+    # to nil.
+    #
+    #   config.timestamp_receipts_with = MyRfc3161TimestampProvider.new
+    #
+    # WHAT THIS SEAM IS FOR. Clickwrap records `recorded_at_by_server`, and calls
+    # it exactly that: the application server's own clock, which the application
+    # controls. An RFC 3161 time-stamp authority
+    # (https://www.rfc-editor.org/info/rfc3161/) or a qualified trust service
+    # supplies something different — a token from a third party over a digest
+    # you gave it, whose value depends entirely on that party, its practice
+    # statement, its certificate status, and what a reader is willing to accept
+    # about it.
+    #
+    # WHAT SUCH A TOKEN CLAIMS. Exactly what that provider supplies and nothing
+    # more. Clickwrap stores the token and the validation status the adapter
+    # reports, and preserves both verbatim; it never upgrades a provider receipt
+    # into a guarantee the provider did not make, never treats a token as
+    # identity, never treats it as a signature by a person, and never restates
+    # it in stronger words than the provider used. If the provider's own status
+    # is "unknown" or "expired", that is what travels into the receipt. eIDAS
+    # gives distinct legal effect to qualified signatures and seals
+    # (https://eur-lex.europa.eu/eli/reg/2014/910/2024-05-20/eng); whether a
+    # given provider's output has that effect is a question about that provider,
+    # not about this gem.
+    #
+    # WHAT THIS FILE DELIBERATELY IS NOT. It is not an RFC 3161 client. Clickwrap
+    # ships no ASN.1 encoder, no HTTP client, and no certificate-chain
+    # validation, and it adds no dependency that would. Timestamping is an
+    # optional integration. A host that needs it supplies an adapter that speaks
+    # to its own chosen authority; assigning this base class is useful only when
+    # an explicit unavailable result is wanted.
+    #
+    # WRITING ONE. Implement `#timestamp(digest)` and `#verify(token, digest)`,
+    # and report honestly from `#capabilities`.
+    # `Configuration#timestamp_receipts_with=` checks that the object responds to
+    # `#timestamp`.
+    class Timestamp
+      # What an adapter returns from `#timestamp`. `issued: false` is an
+      # ordinary outcome — no provider configured, provider unavailable, request
+      # declined — and the record says which rather than leaving a gap where a
+      # token should be.
+      Token = Data.define(:issued, :token, :digest, :provider_name, :protocol, :issued_at, :detail) do
+        def initialize(issued: false, token: nil, digest: nil, provider_name: nil, protocol: nil,
+                       issued_at: nil, detail: nil)
+          super
+        end
+
+        def to_h
+          {
+            "issued" => issued,
+            "token" => token,
+            "digest" => digest,
+            "provider_name" => provider_name,
+            "protocol" => protocol,
+            # The provider's own time, described as the provider's own time.
+            "provider_reported_time" => issued_at && Receipt.format_time(issued_at),
+            "detail" => detail
+          }.compact
+        end
+      end
+
+      # The result of checking a token. `status` carries the provider's own
+      # validation vocabulary unchanged, because "valid according to this
+      # authority today" is a narrower and more useful statement than "valid".
+      Verification = Data.define(:checked, :verified, :status, :provider_name, :protocol, :detail) do
+        def initialize(checked: false, verified: false, status: nil, provider_name: nil,
+                       protocol: nil, detail: nil)
+          super
+        end
+
+        def to_h
+          {
+            "checked" => checked,
+            "verified" => verified,
+            "provider_reported_status" => status,
+            "provider_name" => provider_name,
+            "protocol" => protocol,
+            "detail" => detail
+          }.compact
+        end
+      end
+
+      # Asks the provider to timestamp one digest. Never the raw receipt, never
+      # the personal data inside it: a digest is what a timestamp authority needs
+      # and the only thing it should ever be given.
+      #
+      # Called outside the capture transaction. A provider cannot join a
+      # database transaction, and a capture must never fail because a third
+      # party was slow.
+      def timestamp(digest)
+        Token.new(
+          issued: false,
+          digest: digest,
+          provider_name: provider_name,
+          detail: "This timestamp adapter issues no token, so the only " \
+                  "recorded time remains the application server's own."
+        )
+      end
+
+      # Checks a stored token against the digest it was issued over, and reports
+      # what the provider said. A token nobody re-checks is a stored blob.
+      def verify(_token, _digest)
+        Verification.new(
+          checked: false,
+          verified: false,
+          provider_name: provider_name,
+          detail: "This timestamp adapter issues no token, so there is nothing to check in this " \
+                  "token."
+        )
+      end
+
+      # What this adapter supplies, in the provider's own terms. Read by the
+      # receipt's integrity fragment and by `clickwrap:doctor`, which report the
+      # tier honestly rather than inferring a stronger one from the mere
+      # presence of an adapter.
+      def capabilities
+        {
+          "name" => provider_name,
+          "available" => available?,
+          "protocol" => nil,
+          "supplies" => "Nothing. This is the default placeholder that reports the absence of a " \
+                        "timestamp provider for explicit adapter-contract tests. Configuration " \
+                        "normally remains nil.",
+          "note" => "A configured provider supplies exactly the assurance and validation status " \
+                    "that provider supplies. Clickwrap preserves it and never restates it more " \
+                    "strongly."
+        }
+      end
+
+      def available? = false
+
+      def provider_name = "no_timestamp_provider"
+
+      def to_s = "#{self.class.name} (#{provider_name})"
+    end
+  end
+end

data/lib/clickwrap/ip_geolocation/location.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  module IpGeolocation
+    # One provider's estimate about ONE IP address, at one moment.
+    #
+    # Read that sentence literally, because the whole design follows from it.
+    # This object never describes where a person was. It describes what a
+    # provider's database or edge network said about a network address, with
+    # enough provenance attached that someone reading it in four years can tell
+    # how much weight it deserves. That is why provider name, source, estimated
+    # state, resolution time, and any database or accuracy metadata are members
+    # of the same value object as the country code: a country without the
+    # provider that guessed it, or coordinates without an accuracy radius, read
+    # as far more certain than they are.
+    #
+    # Every member defaults to nil so a resolver fills in only what it actually
+    # has. A resolver must NEVER substitute a placeholder — "Unknown", "XX",
+    # "N/A" — for a field it could not determine. A placeholder is
+    # indistinguishable from a real provider answer once it is written down, and
+    # Clickwrap keeps "we did not collect this", "the provider had no value",
+    # "the lookup failed", and "the provider answered" as four different states.
+    # nil is the honest answer; `unavailable_reason` is how a resolver explains
+    # a failure.
+    #
+    # `to_h` exists because this is a Data object. It is not a persistence
+    # format: the extractor copies out exactly the fields the server-owned
+    # policy authorized, one at a time, and a resolver that gains a new field
+    # upstream never widens what Clickwrap stores by accident.
+    Location = Data.define(
+      :country_code,
+      :country_name,
+      :region_name,
+      :region_code,
+      :city_name,
+      :postal_code,
+      :latitude,
+      :longitude,
+      :timezone,
+      :continent_code,
+      :metro_code,
+      :provider_name,
+      :provider_source,
+      :database_version,
+      :database_sha256,
+      :accuracy_radius_in_kilometers,
+      :accuracy_radius_confidence_percentage,
+      :estimated,
+      :source_was_verified_by_host,
+      :resolved_at,
+      :unavailable_reason
+    ) do
+      # `estimated` defaults to true and `source_was_verified_by_host` to false
+      # because those are the answers that overclaim least. A resolver has to
+      # say something deliberate to move either one, and moving
+      # `source_was_verified_by_host` requires a host decision about its own
+      # network path — never the mere presence of a provider's headers.
+      def initialize(country_code: nil, country_name: nil, region_name: nil, region_code: nil,
+                     city_name: nil, postal_code: nil, latitude: nil, longitude: nil,
+                     timezone: nil, continent_code: nil, metro_code: nil,
+                     provider_name: nil, provider_source: nil, database_version: nil,
+                     database_sha256: nil, accuracy_radius_in_kilometers: nil,
+                     accuracy_radius_confidence_percentage: nil, estimated: true,
+                     source_was_verified_by_host: false, resolved_at: nil,
+                     unavailable_reason: nil)
+        super
+      end
+
+      # The answer a resolver returns when it has nothing to report. It still
+      # names the provider that was asked, because "MaxMind had no row for this
+      # address" and "no resolver was configured at all" are different facts and
+      # a receipt has to be able to tell them apart.
+      def self.unavailable(reason:, provider_name: nil, **provenance)
+        new(unavailable_reason: reason.to_s, provider_name:, **provenance)
+      end
+
+      def unavailable? = !unavailable_reason.to_s.strip.empty?
+
+      # An IP-geolocation result is an estimate about an address. This reader
+      # reports what the resolver said about its own result rather than
+      # hard-coding the answer, but a resolver claiming otherwise still does not
+      # turn an observation about a network address into a statement about where
+      # anyone was, and the receipt goes on labeling the value provider-reported
+      # either way.
+      def estimated? = estimated != false
+
+      # True only when the HOST told Clickwrap that this result arrived over a
+      # path it has verified. No adapter may set it from the presence of a
+      # provider's own headers: headers are attacker-supplied until the
+      # deployment proves otherwise.
+      def source_was_verified_by_host? = source_was_verified_by_host == true
+
+      # Latitude and longitude are one coupled answer. Half a coordinate is not
+      # a result, so nothing downstream is allowed to store one without the
+      # other.
+      def coordinates? = !latitude.nil? && !longitude.nil?
+
+      def accuracy_radius? = !accuracy_radius_in_kilometers.nil?
+
+      # True when the provider actually reported something about the address, as
+      # opposed to handing back a row of blanks. An adapter uses this to turn an
+      # empty answer into an explicit unavailable result with a reason, which is
+      # the whole point of refusing to write "Unknown" into a name column: an
+      # empty result and a real one must never look the same.
+      def any_data_field?
+        [country_code, country_name, region_name, region_code, city_name, postal_code,
+         latitude, longitude, timezone, continent_code, metro_code,
+         accuracy_radius_in_kilometers].any? { |value| !value.nil? }
+      end
+    end
+  end
+end

data/lib/clickwrap/ip_geolocation/null_resolver.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  module IpGeolocation
+    # The resolver Clickwrap uses when the host configured none.
+    #
+    # It exists so that "no IP geolocation provider is installed" is an ordinary
+    # answer with a reason on it, rather than a branch that has to be handled
+    # separately everywhere. Every capture path runs the same code; a host with
+    # no geolocation gem gets `ip_geolocation_unavailable_reason` set to
+    # `no_resolver_configured`, which is a true statement about the application
+    # and reads correctly on a receipt years later.
+    #
+    # That also means the entire request-evidence feature — policies, field
+    # allowlists, retention, receipts, disposal — is testable and reviewable
+    # without a provider account, a database download, or a network call.
+    #
+    # A policy that authorizes IP-geolocation fields while no resolver is
+    # configured is caught earlier, by `Configuration#validate!`, with a
+    # sentence saying so. This resolver is the safety net under that check, not
+    # a way to pretend the configuration is fine.
+    class NullResolver < Resolver
+      REASON = "no_resolver_configured"
+
+      def resolve(_ip_address, http_request: nil)
+        Location.unavailable(reason: REASON)
+      end
+
+      # Nothing. Not "everything but it always fails" — a host reading
+      # `capabilities` is asking what this resolver could ever supply, and the
+      # honest answer is no field at all.
+      def capabilities = [].freeze
+    end
+  end
+end

data/lib/clickwrap/ip_geolocation/resolver.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # IP geolocation adapters.
+  #
+  # Clickwrap has no geolocation dependency and never will. What it has is this
+  # narrow contract, one no-op default that lets the whole feature be exercised
+  # without any provider, a deterministic fixture resolver for tests, and one
+  # optional official adapter for `trackdown`. A host that wants a different
+  # provider writes forty lines against the contract below and configures it.
+  module IpGeolocation
+    # The adapter contract every IP geolocation resolver implements.
+    #
+    #   class MyResolver < Clickwrap::IpGeolocation::Resolver
+    #     def resolve(ip_address, http_request: nil)
+    #       row = MyProvider.lookup(ip_address, http_request:) or
+    #         return Location.unavailable(reason: "provider_had_no_row", provider_name: "my_provider")
+    #
+    #       Location.new(
+    #         country_code: row.country_iso,
+    #         provider_name: "my_provider",
+    #         provider_source: "my_provider_city_database",
+    #         database_version: row.database_build,
+    #         estimated: true,
+    #         resolved_at: Clickwrap.now
+    #       )
+    #     end
+    #
+    #     def capabilities = %i[country]
+    #   end
+    #
+    # Subclassing is optional — `Clickwrap.config.ip_geolocation_resolver`
+    # accepts anything that responds to `#resolve` — but inheriting documents
+    # the intent and gives you the contract's own error messages when a method
+    # is missing.
+    #
+    # Three obligations that are easy to miss, and that the rest of the gem
+    # depends on:
+    #
+    #   1. Return nil ONLY for a field the provider genuinely did not supply.
+    #      Never a placeholder string. "Unknown" written into a country name is
+    #      indistinguishable from a country a provider actually reported, and
+    #      collapsing those two states is exactly what a receipt must not do.
+    #
+    #   2. Say who answered. Set `provider_name`, and `provider_source` when the
+    #      provider has more than one source (a local city database and an edge
+    #      network are not the same evidence). Attach `database_version`,
+    #      `database_sha256`, `accuracy_radius_in_kilometers`, and
+    #      `accuracy_radius_confidence_percentage` whenever the provider gives
+    #      them: the extractor stores that provenance with any coordinate it
+    #      keeps, because coordinates without uncertainty overclaim.
+    #
+    #   3. Never infer trust from a provider's own headers. Leave
+    #      `source_was_verified_by_host` false unless the HOST has explicitly
+    #      told the adapter that its deployment blocks direct origin access or
+    #      sanitizes those headers. A `CF-*` header is a client-supplied string
+    #      until the deployment proves otherwise.
+    #
+    # A resolver is called SYNCHRONOUSLY, before the evidence and domain
+    # transaction opens, so it must be fast and must not raise for ordinary
+    # conditions. A private, loopback, or reserved address is an ordinary
+    # condition: return `Location.unavailable(...)`, do not raise. Clickwrap
+    # rescues a raising resolver and records the failure rather than losing it,
+    # but a reason string you chose is better evidence than an exception class
+    # Clickwrap had to guess a name from.
+    class Resolver
+      # Estimate a location for one observed IP address.
+      #
+      # Returns a Location — populated, or `Location.unavailable(reason:,
+      # provider_name:)`. Returning nil is permitted for an adapter that has
+      # nothing at all to say; Clickwrap records it as `resolver_returned_no_result`,
+      # which is a less useful receipt than a reason you wrote yourself.
+      def resolve(ip_address, http_request: nil)
+        raise NotImplementedError,
+              "#{self.class} must implement #resolve(ip_address, http_request: nil) and return a " \
+              "Clickwrap::IpGeolocation::Location (or nil). See the contract in " \
+              "lib/clickwrap/ip_geolocation/resolver.rb."
+      end
+
+      # Which of `Clickwrap::Vocabulary::IP_GEOLOCATION_DATA_FIELDS` this
+      # resolver can supply at all, as symbols.
+      #
+      # This is a statement about the adapter and its provider, not about any
+      # one lookup: a Cloudflare header set structurally supplies no accuracy
+      # radius, which is a different fact from a MaxMind database that supplies
+      # one but had no value for this address. Clickwrap uses the difference to
+      # explain an empty result honestly, and `clickwrap:doctor` uses it to tell
+      # a host that a policy authorizes a field its resolver can never fill.
+      def capabilities
+        raise NotImplementedError,
+              "#{self.class} must implement #capabilities and return the subset of " \
+              "Clickwrap::Vocabulary::IP_GEOLOCATION_DATA_FIELDS it can supply, as symbols. " \
+              "Return [] if it can supply none."
+      end
+    end
+  end
+end

data/lib/clickwrap/ip_geolocation/static_resolver.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  module IpGeolocation
+    # A resolver that answers from a fixed table of addresses.
+    #
+    #   Clickwrap.config.ip_geolocation_resolver =
+    #     Clickwrap::IpGeolocation::StaticResolver.new(
+    #       "203.0.113.10" => {
+    #         country_code: "ES",
+    #         country_name: "Spain",
+    #         city_name: "Madrid",
+    #         latitude: 40.4168,
+    #         longitude: -3.7038,
+    #         accuracy_radius_in_kilometers: 20,
+    #         provider_source: "test_city_database",
+    #         database_version: "2026-08-01"
+    #       }
+    #     )
+    #
+    # This is what the gem's own tests run against, and it is the right resolver
+    # for a host's test and development environments too. A real provider makes
+    # request-evidence tests non-deterministic in the one place where
+    # determinism matters most: an assertion about exactly which fields a policy
+    # stored has to fail because the ALLOWLIST changed, never because a database
+    # was rebuilt or an address was reassigned between two runs.
+    #
+    # Values may be given as attribute hashes or as Location objects. An address
+    # that is not in the table resolves to an explicit unavailable result — not
+    # to a blank one, and not to a plausible-looking default, because a fixture
+    # that quietly invents a country is a test that proves nothing.
+    class StaticResolver < Resolver
+      PROVIDER_NAME = "static_ip_geolocation_fixture"
+      NO_FIXTURE_REASON = "no_fixture_for_this_ip_address"
+
+      # The fixture table can be written straight into the call, which is how it
+      # reads best in a test:
+      #
+      #   StaticResolver.new("203.0.113.10" => { country_code: "ES" })
+      #
+      # Ruby hands a trailing bare hash over as keyword arguments, so those
+      # addresses arrive in `fixtures` and are merged with the positional form
+      # below. Wrap the table in braces when you also pass an option:
+      #
+      #   StaticResolver.new({ "203.0.113.10" => { ... } }, capabilities: %i[country])
+      #
+      # `capabilities:` is worth setting deliberately. It models what a provider
+      # can supply AT ALL, which is a different fact from what it happened to
+      # return for one address: a Cloudflare visitor-header set supplies no
+      # accuracy radius ever, while a MaxMind city database supplies one but may
+      # have no value for a particular address. Clickwrap explains an empty
+      # result differently in those two cases, so a fixture that wants to
+      # exercise the Cloudflare shape should say
+      # `capabilities: %i[country region city latitude_and_longitude timezone]`.
+      def initialize(locations_by_ip_address = {}, capabilities: nil, provider_name: PROVIDER_NAME,
+                     **fixtures)
+        super()
+        # Written as an explicit keyword, the table lands in `fixtures` like any
+        # other trailing hash. Take it back out so both spellings mean the same
+        # thing, rather than one of them quietly building a table with a single
+        # nonsense entry named after the parameter.
+        declared = fixtures.delete(:locations_by_ip_address).to_h
+
+        @provider_name = provider_name.to_s
+        @locations_by_ip_address = build_table(locations_by_ip_address.to_h.merge(declared).merge(fixtures)).freeze
+        @capabilities = normalize_capabilities(capabilities).freeze
+
+        freeze
+      end
+
+      attr_reader :capabilities
+
+      def resolve(ip_address, http_request: nil)
+        @locations_by_ip_address.fetch(ip_address.to_s.strip) do
+          Location.unavailable(reason: NO_FIXTURE_REASON, provider_name: @provider_name)
+        end
+      end
+
+      private
+
+      def build_table(declaration)
+        declaration.to_h { |ip_address, location| [ip_address.to_s.strip, build_location(location)] }
+      end
+
+      # A fixture written as a hash still comes back as a fully formed result:
+      # provider name and resolution time are filled in when the hash omits
+      # them, because a stored IP-geolocation value without its provenance is
+      # exactly what the extractor refuses to write, and a fixture that could
+      # not survive that rule would be testing the wrong thing.
+      def build_location(location)
+        return location if location.is_a?(Location)
+
+        attributes = location.to_h.transform_keys(&:to_sym)
+        attributes[:provider_name] ||= @provider_name
+        attributes[:resolved_at] ||= Clickwrap.now
+
+        Location.new(**attributes)
+      end
+
+      def normalize_capabilities(declared)
+        return Vocabulary::IP_GEOLOCATION_DATA_FIELDS.map(&:to_sym) if declared.nil?
+
+        Array(declared).map { |field| field.to_s.to_sym }
+      end
+    end
+  end
+end