clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/linter.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # Development and test heuristics for the presentation layer.
+  #
+  # ============================================================================
+  # THESE ARE HEURISTICS. They warn; they never raise, never block a render, and
+  # never certify anything. A clean run means "none of the specific hazards
+  # below were detected in what was inspected" and nothing else.
+  #
+  # This class must never print, return, or imply "compliant", "enforceable",
+  # "legally binding", "accessible", or "approved". Courts assess the complete
+  # page in context and accessibility applies to the whole experience, so no
+  # library that sees one fragment of one template can make any of those calls.
+  # What it can do is notice objectively checkable mistakes — a submit button
+  # above the controls, a consent box that arrives already ticked, a document
+  # nobody can open — and say so in a full sentence.
+  # ============================================================================
+  #
+  #   findings = Clickwrap::Linter.review_policy(Clickwrap.policy!(:signup))
+  #   findings.map(&:code)         # => [:consent_statement_bundles_purposes]
+  #   findings.first.explanation   # => a plain-English sentence
+  #
+  # Every finding carries a stable symbol, so a test can assert on it without
+  # matching English, and an explanation, so a person reading the log knows what
+  # to do about it.
+  class Linter
+    Finding = Data.define(:code, :explanation, :context) do
+      def to_s = "#{code}: #{explanation}"
+    end
+
+    # Rendered-fragment scans, kept to string work so they are cheap enough to
+    # run on every development render.
+    ANSWER_FIELD_PATTERN = /name=["']clickwrap_submission\[answers\]\[([^\]"']+)\]["']/
+    TOKEN_FIELD_PATTERN = /name=["']clickwrap_submission\[presentation_token\]["']/
+    SUBMIT_CONTROL_PATTERN = /<(?:button|input)\b[^>]*type=["']submit["']|<button(?![^>]*type=)/i
+    CHECKED_ATTRIBUTE_PATTERN = /\bchecked\b/
+
+    # A rough test for a consent sentence that is carrying more than one
+    # purpose. It is deliberately generous: the cost of a false positive is one
+    # log line suggesting a split, and the cost of a false negative is a consent
+    # record whose meaning nobody can reconstruct.
+    BUNDLED_PURPOSE_PATTERN = %r{\b(and|and/or|as well as|plus)\b}i
+
+    class << self
+      # On in development and test, off everywhere else — a production request
+      # should not be scanning its own HTML — and `config.lint_presentations`
+      # answers for a host that disagrees with either half.
+      #
+      # Every finding is a log line, never an exception: a lint finding is a
+      # thing to look at, not a reason to stop a developer's page from
+      # rendering. Which is exactly why it needs a switch — a warning nobody
+      # can turn off is one people learn to scroll past.
+      def enabled?
+        configured = Clickwrap.config.lint_presentations
+        return configured unless configured.nil?
+
+        return false unless defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env
+
+        ::Rails.env.development? || ::Rails.env.test?
+      end
+
+      # --- Entry points -------------------------------------------------------
+
+      # What a compiled policy alone can be checked for, without rendering
+      # anything: blank copy, bundled consent purposes, and an optional consent
+      # that another statement has quietly made mandatory.
+      def review_policy(policy, locale: nil)
+        locale = (locale || (defined?(::I18n) ? ::I18n.locale : :en)).to_s
+
+        findings = []
+        findings.concat(blank_assertion_findings(policy))
+        findings.concat(bundled_consent_findings(policy, locale))
+        findings.concat(optional_consent_prerequisite_findings(policy))
+        findings
+      end
+
+      # What one presentation can be checked for: a statement the person is
+      # asked to accept with no way to read what they are accepting.
+      def review_presentation(presentation)
+        presentation.statements.filter_map do |statement|
+          next if statement.documents.any?
+          next unless %w[agreement acknowledgment consent].include?(statement.kind)
+
+          Finding.new(
+            code: :document_link_missing,
+            explanation: "The #{statement.kind} #{statement.key.inspect} presents no document, so " \
+                         "the person is asked to accept something the page never shows them. Give " \
+                         "the statement a `document:` and publish it.",
+            context: { statement: statement.key, policy: presentation.policy_key }
+          )
+        end
+      end
+
+      # Whether the manifest that came back still says what the policy says.
+      # A difference here means the evidence and the current server-owned offer
+      # have diverged — usually a deploy between render and submit, sometimes a
+      # hand-built form that stopped tracking the policy.
+      def review_manifest(manifest, policy:)
+        snapshot = manifest.respond_to?(:to_h) ? manifest.to_h : manifest
+        rendered = Array(snapshot["statements"] || snapshot[:statements])
+        differences = manifest_differences(rendered, policy: policy, locale: snapshot["locale"])
+        return [] if differences.empty?
+
+        [Finding.new(
+          code: :rendered_manifest_differs_from_policy,
+          explanation: "The submitted presentation manifest does not match the current policy " \
+                       "#{policy.key}: #{differences.join("; ")}. Clickwrap verifies this at " \
+                       "capture; the warning is here so the drift is visible while you can still " \
+                       "explain it.",
+          context: { policy: policy.key, differences: differences }
+        )]
+      end
+
+      # What the rendered HTML can be checked for. Pass the whole page when you
+      # have it — the CTA-ordering check needs everything before the block, not
+      # just the block.
+      def review_rendered_html(html, presentation: nil)
+        text = html.to_s
+        findings = []
+        findings.concat(submit_ordering_findings(text))
+        findings.concat(submit_button_text_findings(text, presentation)) if presentation
+        findings.concat(preselected_control_findings(text))
+        if presentation
+          findings.concat(rendered_document_link_findings(text, presentation))
+          findings.concat(combined_control_findings(text, presentation))
+        end
+        findings
+      end
+
+      # Called by the form-builder helper on every development render. Scans
+      # only the fragment it produced, so it deliberately skips the CTA-ordering
+      # check (a submit button earlier in the host's page is invisible from
+      # here — that one belongs in a system test over the whole page).
+      def review_rendered_fields(html, presentation:)
+        findings = preselected_control_findings(html.to_s)
+        findings.concat(rendered_document_link_findings(html.to_s, presentation))
+        findings.concat(combined_control_findings(html.to_s, presentation))
+        findings.concat(review_presentation(presentation))
+        warn_about(findings, source: "policy #{presentation.policy_key}")
+        findings
+      end
+
+      # Warnings go to the Rails log, or to stderr when there is no log. Never
+      # an exception: a lint finding is a thing to look at, not a reason to stop
+      # a developer's page from rendering.
+      def warn_about(findings, source: nil)
+        Array(findings).each do |finding|
+          message = ["[clickwrap] lint", source, "#{finding.code}: #{finding.explanation}"]
+                    .compact.join(" — ")
+
+          logger = Clickwrap.logger
+          logger ? logger.warn(message) : Kernel.warn(message)
+        end
+
+        findings
+      end
+
+      private
+
+      # --- Policy checks ------------------------------------------------------
+
+      def blank_assertion_findings(policy)
+        policy.statements.filter_map do |statement|
+          next if statement.assertion.present?
+
+          Finding.new(
+            code: :assertion_text_blank,
+            explanation: "Statement #{statement.key.inspect} has no assertion text. The sentence " \
+                         "beside the control is what the receipt records, so a blank one records " \
+                         "nothing meaningful.",
+            context: { policy: policy.key, statement: statement.key }
+          )
+        end
+      end
+
+      def bundled_consent_findings(policy, locale)
+        policy.consent_statements.filter_map do |statement|
+          reasons = []
+          reasons << "it presents #{statement.document_keys.size} documents" if statement.document_keys.size > 1
+          if BUNDLED_PURPOSE_PATTERN.match?(resolved_assertion(statement, locale))
+            reasons << "its sentence joins more than one thing with a conjunction"
+          end
+          next if reasons.empty?
+
+          Finding.new(
+            code: :consent_statement_bundles_purposes,
+            explanation: "Consent statement #{statement.key.inspect} may cover more than one " \
+                         "purpose (#{reasons.join(" and ")}). One control per purpose keeps each " \
+                         "grant separately withdrawable and keeps the receipt able to say which " \
+                         "purpose was actually agreed to.",
+            context: { policy: policy.key, statement: statement.key }
+          )
+        end
+      end
+
+      # The words a person would actually read, which is what these heuristics
+      # are about. An assertion declared as an I18n key says nothing on its own;
+      # when it cannot be resolved (no translation yet), fall back to the
+      # declaration rather than turning a lint pass into a failure.
+      def resolved_assertion(statement, locale)
+        statement.resolve_copy(locale: locale)["assertion"].to_s
+      rescue StandardError
+        statement.assertion.to_snapshot.to_s
+      end
+
+      def optional_consent_prerequisite_findings(policy)
+        optional_consents = policy.consent_statements.select(&:optional?).map(&:key)
+        return [] if optional_consents.empty?
+
+        policy.statements.flat_map do |statement|
+          (statement.requires & optional_consents).map do |consent_key|
+            Finding.new(
+              code: :optional_consent_required_for_another_action,
+              explanation: "#{statement.key.inspect} requires the optional consent " \
+                           "#{consent_key.inspect}, which makes an optional control mandatory for " \
+                           "an action it is not part of. Either drop `optional: true` and say " \
+                           "plainly that it is required, or stop requiring it here.",
+              context: { policy: policy.key, statement: statement.key, consent: consent_key }
+            )
+          end
+        end
+      end
+
+      # --- Manifest checks ----------------------------------------------------
+
+      def manifest_differences(rendered, policy:, locale:)
+        rendered_keys = rendered.map { |fragment| fragment["key"] || fragment[:key] }
+        policy_keys = policy.statements.map(&:key)
+
+        differences = (policy_keys - rendered_keys).map { |key| "#{key} is in the policy but absent from the manifest" }
+        (rendered_keys - policy_keys).each { |key| differences << "#{key} is in the manifest but not the policy" }
+
+        rendered.each do |fragment|
+          statement = policy.statement(fragment["key"] || fragment[:key])
+          next if statement.nil?
+
+          differences.concat(statement_differences(fragment, statement, locale))
+        end
+
+        differences
+      end
+
+      def statement_differences(fragment, statement, locale)
+        differences = []
+        differences << "#{statement.key} is recorded in the manifest as required=#{fragment["required"]}" if
+          fragment.key?("required") && fragment["required"] != statement.required?
+
+        resolved_locale = (locale || (defined?(::I18n) ? ::I18n.locale : :en)).to_s
+        resolved = statement.resolve_copy(locale: resolved_locale)["assertion"]
+        differences << "#{statement.key} has different wording in the manifest" if
+          fragment["assertion"].present? && resolved.present? && fragment["assertion"] != resolved
+
+        differences
+      end
+
+      # --- Rendered-HTML checks -----------------------------------------------
+
+      # Also unchanged by the composed line: whether the block is one control or
+      # five, the question is whether a person can reach the action without
+      # passing it, and the first answer field is still where the block starts.
+      def submit_ordering_findings(html)
+        first_control = html.index(ANSWER_FIELD_PATTERN) || html.index(TOKEN_FIELD_PATTERN)
+        return [] if first_control.nil?
+
+        first_submit = html.index(SUBMIT_CONTROL_PATTERN)
+        return [] if first_submit.nil? || first_submit > first_control
+
+        [Finding.new(
+          code: :submit_control_before_clickwrap_block,
+          explanation: "A submit control appears before the Clickwrap controls in this page. " \
+                       "Someone can reach the action without having passed what they are being " \
+                       "asked to accept; put the block immediately before the call to action it " \
+                       "belongs to.",
+          context: { submit_at: first_submit, controls_at: first_control }
+        )]
+      end
+
+      # Unchanged by the composed line, and deliberately so: the composed
+      # control is submitted under a real statement's name, so a `checked` on
+      # one box covering three acts is caught by exactly the same scan that
+      # catches a `checked` on a box covering one.
+      def preselected_control_findings(html)
+        findings = []
+        position = 0
+
+        while (match = ANSWER_FIELD_PATTERN.match(html, position))
+          position = match.end(0)
+          statement_key = match[1]
+          next unless CHECKED_ATTRIBUTE_PATTERN.match?(surrounding_tag(html, match.begin(0)))
+
+          findings << Finding.new(
+            code: :consent_control_preselected,
+            explanation: "The control for #{statement_key.inspect} is rendered already selected. " \
+                         "A pre-ticked box records the page's default rather than a person's " \
+                         "action; controls must start empty and stay empty until someone acts.",
+            context: { statement: statement_key }
+          )
+        end
+
+        findings
+      end
+
+      # The composed line's own hazard, and the reason it needs a rule of its
+      # own: this presentation signed ONE control covering several statements,
+      # and the page rendered controls for the covered ones as well. Usually an
+      # ejected view that predates the composed default.
+      #
+      # It is not a security hole — the server fans the one signed control's
+      # answer out to every statement it covers and overwrites whatever else
+      # arrived — but it is a page offering choices that do not exist. Somebody
+      # unticks one box, submits, and gets a refusal about a statement they
+      # thought they had answered separately.
+      def combined_control_findings(html, presentation)
+        combined = presentation.try(:combined)
+        return [] if combined.nil?
+
+        extra = html.scan(ANSWER_FIELD_PATTERN).flatten.uniq &
+                (combined.statement_keys - [combined.answered_as])
+        return [] if extra.empty?
+
+        [Finding.new(
+          code: :combined_statement_rendered_as_its_own_control,
+          explanation: "This presentation offers one control for " \
+                       "#{combined.statement_keys.join(", ")}, but the page also renders separate " \
+                       "controls for #{extra.join(", ")}. The server answers every covered " \
+                       "statement from the one signed control, so those extra boxes offer a " \
+                       "choice nobody has — render the composed sentence, or present with " \
+                       "`combined: false` and mean it.",
+          context: { policy: presentation.policy_key, covered: combined.statement_keys, extra: extra }
+        )]
+      end
+
+      def rendered_document_link_findings(html, presentation)
+        rendered_paths = Loofah.fragment(html).css("a[href]").map { |link| link["href"] }
+
+        presentation.statements.flat_map do |statement|
+          statement.documents.filter_map do |document|
+            next if document.path.present? && rendered_paths.include?(document.path)
+
+            Finding.new(
+              code: :document_link_missing,
+              explanation: "#{document.key.inspect} is part of #{statement.key.inspect}, but the " \
+                           "exact immutable path signed into the presentation " \
+                           "(#{document.path.inspect}) was not rendered as a link. A matching label " \
+                           "that points somewhere else is not the offered document version.",
+              context: { statement: statement.key, document: document.key, expected_path: document.path }
+            )
+          end
+        end
+      end
+
+      def submit_button_text_findings(html, presentation)
+        expected = presentation.submit_button_text
+        return [] if expected.blank?
+
+        fragment = Loofah.fragment(html)
+        control = fragment.css("input[type='submit'], button[type='submit'], button:not([type])").first
+        return [] unless control
+
+        actual = control.name == "input" ? control["value"] : control.text
+        return [] if actual == expected
+
+        [Finding.new(
+          code: :submit_button_text_differs_from_manifest,
+          explanation: "The presentation records #{expected.inspect} as its call to action, but " \
+                       "the rendered submit control says #{actual.inspect}. Render the action with " \
+                       "form.clickwrap or form.clickwrap_submit so one string supplies both.",
+          context: { expected: expected, actual: actual }
+        )]
+      end
+
+      # The opening tag the match sits inside, so `checked` on a neighboring
+      # element is not mistaken for `checked` on this control.
+      def surrounding_tag(html, position)
+        start = html.rindex("<", position) || position
+        finish = html.index(">", position) || html.length
+        html[start..finish]
+      end
+    end
+  end
+end

data/lib/clickwrap/localized_text.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # Every human-facing string in a policy — an assertion, a label, a link
+  # label, a call to action — can be written three ways:
+  #
+  #   statement: "I agree to the Terms."          # a literal
+  #   statement: :"clickwrap.signup.terms"        # an I18n key
+  #   statement: { en: "I agree", es: "Acepto" }  # a locale map
+  #
+  # Whichever form the policy uses, Clickwrap resolves it to actual text before
+  # the presentation is built, and stores the resolved text and locale in the
+  # evidence. Storing only an I18n key would be a false economy: the key's
+  # meaning can change in a later deploy, and then the receipt no longer says
+  # what the server bound to the presentation.
+  #
+  # A missing translation fails closed. Presenting a required legal statement
+  # as a raw key, a blank string, or an unexpected fallback language would put
+  # something in front of a person and then record it as though it had been
+  # legible to them.
+  class LocalizedText
+    attr_reader :declaration
+
+    def initialize(declaration)
+      @declaration = declaration
+      freeze
+    end
+
+    # Returns [text, locale_actually_used].
+    def resolve(locale:, interpolations: {})
+      case declaration
+      when String then [declaration, locale.to_s]
+      when Symbol then resolve_i18n_key(locale, interpolations)
+      when Hash then resolve_locale_map(locale)
+      when Proc then [declaration.call(locale).to_s, locale.to_s]
+      when nil then [nil, nil]
+      else
+        raise DefinitionError,
+              "A policy text must be a String, an I18n key Symbol, a locale Hash, or a " \
+              "callable, got #{declaration.class}"
+      end
+    end
+
+    def present? = !declaration.nil?
+
+    # How the declaration appears in the compiled policy snapshot. The snapshot
+    # records the shape, not the resolved text, because the same revision
+    # legitimately renders differently per locale.
+    def to_snapshot
+      case declaration
+      when String then { "kind" => "literal", "value" => declaration }
+      when Symbol then { "kind" => "i18n_key", "value" => declaration.to_s }
+      when Hash then { "kind" => "locale_map", "value" => declaration.transform_keys(&:to_s).transform_values(&:to_s) }
+      when Proc then { "kind" => "callable" }
+      end
+    end
+
+    private
+
+    def resolve_i18n_key(locale, interpolations)
+      unless defined?(::I18n)
+        raise DefinitionError,
+              "#{declaration.inspect} looks like an I18n key but I18n is not loaded. " \
+              "Use a literal string or a locale map instead."
+      end
+
+      text = ::I18n.t(declaration, locale:, default: nil, **interpolations)
+
+      raise MissingTranslation.new(key: declaration, locale:) if text.nil? || text.to_s.strip.empty?
+
+      [text.to_s, locale.to_s]
+    end
+
+    def resolve_locale_map(locale)
+      normalized = declaration.transform_keys(&:to_s)
+      wanted = locale.to_s
+
+      text = normalized[wanted] || normalized[wanted.split("-").first]
+
+      raise MissingTranslation.new(key: declaration.keys, locale:) if text.nil?
+
+      [text.to_s, wanted]
+    end
+  end
+
+  # Raised when a required human-facing string has no text for the requested
+  # locale. Clickwrap will not present a legal statement in a language the
+  # policy did not declare, and will not record one it could not render.
+  class MissingTranslation < DefinitionError
+    attr_reader :key, :locale
+
+    def initialize(key:, locale:)
+      @key = key
+      @locale = locale
+      super(
+        "No text for #{key.inspect} in locale #{locale.inspect}. Add the translation, or " \
+        "restrict the policy to the locales it can actually present."
+      )
+    end
+  end
+end

data/lib/clickwrap/macros.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The host-facing macro. The engine extends `ActiveRecord::Base` with this
+  # module (via `ActiveSupport.on_load(:active_record)`), so the actor model can
+  # declare:
+  #
+  #   class User < ApplicationRecord
+  #     has_clickwraps
+  #   end
+  #
+  # That gives the model its evidence proxy — `user.clickwraps.agreed_to?(:terms)`
+  # and friends — plus the associations, without Clickwrap reaching into the
+  # model for anything else. Same grammar as the rest of the ecosystem:
+  # `has_sessions`, `has_credits`, `has_api_keys`, `has_wallets`.
+  #
+  # Note what the macro deliberately does NOT add: a `dependent: :destroy` on
+  # the evidence association. Deleting an account must not silently erase the
+  # record of what that person agreed to; the associations nullify the actor
+  # link and leave a stable pseudonymous reference behind, and what happens next
+  # is a retention decision the host makes on purpose.
+  #
+  # The macro is a thin forwarder — all behavior lives in Clickwrap::HasClickwraps
+  # so it is discoverable, testable, and `include`-able directly when a host
+  # prefers that style.
+  #
+  # We don't `require_relative` the concern here even though this file is
+  # required by the spine at gem-load time. The concern lives under
+  # `lib/clickwrap/models/concerns/` and is autoloaded by Zeitwerk (the engine
+  # pushes that subtree under the `Clickwrap` namespace with `models` and
+  # `concerns` collapsed). Requiring it here too would double-manage the same
+  # constant and make Zeitwerk raise on its eager-load pass. This is safe
+  # because the macro body only REFERENCES the constant, and it runs when a host
+  # model calls `has_clickwraps` — long after boot, when the autoloader is
+  # fully wired.
+  module Macros
+    def has_clickwraps
+      include Clickwrap::HasClickwraps unless include?(Clickwrap::HasClickwraps)
+      self
+    end
+
+    # For a domain row whose existence was authorized by a clickwrap capture —
+    # a withdrawal, a signed declaration, a provisioned contract. Expects a
+    # `clickwrap_event_id` column (`bin/rails generate clickwrap:link
+    # your_table` writes the migration) and an explicit evidence contract:
+    #
+    #   has_clickwrap_evidence policy: :withdrawal_authorization,
+    #                          statement: :withdrawal,
+    #                          actor: :user,
+    #                          subject: :self
+    #
+    # It then reads aloud from either end:
+    #
+    #   capture_clickwrap_and!(:withdrawal_authorization) do |pending_receipt|
+    #     withdrawal.clickwrap_event_id = pending_receipt.event_id
+    #     withdrawal.save!
+    #   end
+    #
+    #   withdrawal.clickwrap_event      # the evidence event behind this row
+    #   withdrawal.clickwrap_receipt    # its receipt: .verify, .to_canonical_json
+    #
+    # No database foreign key, deliberately: evidence and domain rows keep
+    # independent retention schedules. The model contract is still strict for
+    # every new link: it checks the policy, statement, human actor, subject,
+    # tenant, and represented party, and it never lets a link be replaced.
+    # Rows that predate the gem may remain nil; new rows require evidence by
+    # default.
+    def has_clickwrap_evidence(policy:, statement:, actor:, subject:, tenant: nil,
+                               represented_party: nil, required_for_new_records: true)
+      belongs_to :clickwrap_event, class_name: "Clickwrap::Event", optional: true
+
+      class_attribute :clickwrap_evidence_contract, instance_writer: false
+      self.clickwrap_evidence_contract = {
+        policy: policy.to_s,
+        statement: statement.to_s,
+        actor: actor,
+        subject: subject,
+        tenant: tenant,
+        represented_party: represented_party,
+        required_for_new_records: required_for_new_records == true
+      }.freeze
+
+      validate :validate_clickwrap_evidence_is_present_for_new_record
+      validate :validate_clickwrap_evidence_link_cannot_be_replaced
+      validate :validate_clickwrap_evidence_matches_this_record
+
+      define_method(:clickwrap_receipt) do
+        self.class.column_names.include?("clickwrap_event_id") ? clickwrap_event&.receipt : nil
+      end
+
+      define_method(:validate_clickwrap_evidence_is_present_for_new_record) do
+        # A host may deploy the model macro before the link migration, and old
+        # data migrations may load today's model while replaying a schema from
+        # before Clickwrap existed. The contract becomes strict as soon as the
+        # column exists; before then there is no attribute that could carry the
+        # evidence, so the macro must stay inert instead of crashing deploys.
+        # Class-level `column_names`, never per-row `has_attribute?`: a partial
+        # SELECT must not read as "this row has no evidence contract".
+        return unless self.class.column_names.include?("clickwrap_event_id")
+
+        contract = self.class.clickwrap_evidence_contract
+        return unless new_record? && contract.fetch(:required_for_new_records)
+        return if clickwrap_event_id.present?
+
+        errors.add(
+          :clickwrap_event,
+          "must be linked inside the Clickwrap protected-action transaction"
+        )
+      end
+
+      define_method(:validate_clickwrap_evidence_link_cannot_be_replaced) do
+        return unless self.class.column_names.include?("clickwrap_event_id")
+        return unless persisted? && will_save_change_to_clickwrap_event_id?
+
+        previous_id, next_id = clickwrap_event_id_change_to_be_saved
+        return if previous_id.blank? || previous_id == next_id
+
+        errors.add(
+          :clickwrap_event,
+          "cannot be replaced or removed after it has been linked"
+        )
+      end
+
+      define_method(:validate_clickwrap_evidence_matches_this_record) do
+        return unless self.class.column_names.include?("clickwrap_event_id")
+
+        should_validate = new_record? || will_save_change_to_clickwrap_event_id?
+        return unless should_validate && clickwrap_event_id.present?
+
+        event = Clickwrap::Event.find_by(id: clickwrap_event_id)
+        unless event
+          errors.add(:clickwrap_event, "does not identify an existing Clickwrap event")
+          next
+        end
+
+        contract = self.class.clickwrap_evidence_contract
+        expected_policy = Clickwrap.policy!(contract.fetch(:policy))
+        expected_statement = expected_policy.statement!(contract.fetch(:statement))
+
+        mismatches = []
+        mismatches << "a capture event" unless event.event_type == "capture"
+        mismatches << "policy #{expected_policy.key.inspect}" unless event.policy_key == expected_policy.key
+
+        statement_event = event.statements.find do |candidate|
+          candidate.statement_key == expected_statement.key &&
+            candidate.action == expected_statement.initial_action
+        end
+        mismatches << "statement #{expected_statement.key.inspect}" unless statement_event
+
+        expected_actor = clickwrap_evidence_contract_value(contract.fetch(:actor), :actor)
+        mismatches << "this record's actor" unless
+          event.actor_reference == Clickwrap::Reference.actor(expected_actor)
+
+        expected_subject = clickwrap_evidence_contract_value(contract.fetch(:subject), :subject)
+        unless event.subject_key.to_s == Clickwrap::Reference.subject(expected_subject).to_s
+          mismatches << "this record's subject"
+        end
+
+        expected_tenant = clickwrap_evidence_contract_value(contract.fetch(:tenant), :tenant)
+        unless event.tenant_key.to_s == Clickwrap::Reference.tenant(expected_tenant).to_s
+          mismatches << "this record's tenant"
+        end
+
+        expected_party = clickwrap_evidence_contract_value(
+          contract.fetch(:represented_party),
+          :represented_party
+        )
+        unless event.represented_party_reference.to_s ==
+               Clickwrap::Reference.represented_party(expected_party).to_s
+          mismatches << "this record's represented party"
+        end
+
+        next unless mismatches.any?
+
+        errors.add(
+          :clickwrap_event,
+          "must be #{mismatches.to_sentence}; the supplied event belongs to a different act"
+        )
+      end
+
+      define_method(:clickwrap_evidence_contract_value) do |resolver, name|
+        case resolver
+        when :self
+          self
+        when Symbol, String
+          public_send(resolver)
+        else
+          resolver.respond_to?(:call) ? resolver.call(self) : resolver
+        end
+      rescue NoMethodError => error
+        raise DefinitionError,
+              "The `#{name}:` resolver for #{self.class.name}.has_clickwrap_evidence could not " \
+              "be called: #{error.message}"
+      end
+
+      private :validate_clickwrap_evidence_is_present_for_new_record,
+              :validate_clickwrap_evidence_link_cannot_be_replaced,
+              :validate_clickwrap_evidence_matches_this_record,
+              :clickwrap_evidence_contract_value
+      self
+    end
+  end
+end