clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/services/validate_policy_references.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Clickwrap
+  module Services
+    # The policy DSL compiles each declaration immediately, while references may
+    # legitimately point at a declaration in a later file. This second pass runs
+    # after every file has loaded and resolves those names as one graph. A typo
+    # therefore fails boot, never the first production capture.
+    class ValidatePolicyReferences
+      def self.call = new.call
+
+      def call
+        Clickwrap.policies.each do |policy|
+          validate_documents!(policy)
+          retention_class = validate_retention_class!(policy)
+          validate_request_evidence_retention!(policy, retention_class)
+          validate_host_calculations!(policy, retention_class)
+          validate_authority_adapter!(policy)
+          validate_ip_geolocation_resolver!(policy)
+        end
+
+        true
+      end
+
+      # Routes are not knowable while Rails is still drawing them. The engine
+      # invokes this method from `after_routes_loaded`; non-Rails users still get
+      # syntax validation from Statement itself.
+      def self.validate_remediation_paths!
+        return true unless defined?(::Rails) && ::Rails.respond_to?(:application)
+        return true unless ::Rails.application
+
+        Clickwrap.policies.each do |policy|
+          policy.consent_statements.each do |statement|
+            validate_remediation_path!(policy, statement)
+          end
+        end
+
+        true
+      end
+
+      class << self
+        private
+
+        def validate_remediation_path!(policy, statement)
+          value = statement.withdrawal_path.to_s
+          uri = URI.parse(value)
+          return if %w[http https].include?(uri.scheme) && uri.host.present?
+
+          unless uri.scheme.nil? && value.start_with?("/")
+            raise DefinitionError,
+                  "Consent statement #{statement.key} in policy #{policy.key} has withdrawal " \
+                  "path #{value.inspect}. Use an absolute application path beginning with `/`, " \
+                  "or a complete `https://` URL."
+          end
+
+          ::Rails.application.routes.recognize_path(uri.path, method: :get)
+        rescue URI::InvalidURIError
+          raise DefinitionError,
+                "Consent statement #{statement.key} in policy #{policy.key} has malformed " \
+                "withdrawal path #{value.inspect}. Give it the exact page a person can visit."
+        rescue ActionController::RoutingError
+          raise DefinitionError,
+                "Consent statement #{statement.key} in policy #{policy.key} points at " \
+                "#{value.inspect}, but the host has no GET route for that path. Add the route or " \
+                "correct `withdrawal_path:` so consent is not easier to give than to withdraw."
+        end
+      end
+
+      private
+
+      def validate_documents!(policy)
+        policy.document_keys.each do |document_key|
+          definitions = Clickwrap.documents.values.select { |definition| definition.key == document_key }
+          if definitions.empty?
+            raise DefinitionError,
+                  "Policy #{policy.key} presents document #{document_key.inspect}, but no " \
+                  "`Clickwrap.document #{document_key.to_sym.inspect}, ...` declaration exists. " \
+                  "(A statement's document defaults to its own key; if this statement is about " \
+                  "an operational fact with no published document — the statement text itself " \
+                  "is the whole notice — say so with `document: nil`.)"
+          end
+
+          next if policy.locales.nil?
+
+          available = definitions.map(&:locale).uniq
+          missing = policy.locales - available
+          next if missing.empty?
+
+          raise DefinitionError,
+                "Policy #{policy.key} can be presented in #{missing.join(", ")}, but document " \
+                "#{document_key.inspect} has no declaration in #{missing.join(", ")}. Declare " \
+                "one immutable version per permitted locale."
+        end
+      end
+
+      def validate_retention_class!(policy)
+        Clickwrap.retention_classes[policy.retention_class_key] ||
+          raise(
+            DefinitionError,
+            "Policy #{policy.key} says `retain_with #{policy.retention_class_key.to_sym.inspect}`, " \
+            "but no retention class with that key is declared. Define it with " \
+            "`Clickwrap.retention #{policy.retention_class_key.to_sym.inspect} do ... end`."
+          )
+      end
+
+      def validate_request_evidence_retention!(policy, retention_class)
+        RequestEvidencePolicy::FIELD_CATEGORIES.each do |category|
+          setting = policy.request_evidence.setting_for(category)
+          next unless setting.record?
+          next if setting.delete_after || setting.retain_until || retention_class.rule_for(category)
+
+          raise DefinitionError,
+                "Policy #{policy.key} records #{category}, but neither that policy nor retention " \
+                "class #{retention_class.key} says when to dispose of it. Add " \
+                "`delete_after:`/`retain_until:` to the policy or the matching plain-English " \
+                "request-evidence rule to the retention class."
+        end
+      end
+
+      def validate_host_calculations!(policy, retention_class)
+        referenced = retention_class.rules.values.filter_map do |rule|
+          rule.host_event_name&.to_sym
+        end
+        referenced.concat(
+          RequestEvidencePolicy::FIELD_CATEGORIES.filter_map do |category|
+            policy.request_evidence.setting_for(category).retain_until&.to_sym
+          end
+        )
+
+        missing = referenced.uniq - Clickwrap.config.retention_time_calculator_names
+        return if missing.empty?
+
+        raise DefinitionError,
+              "Policy #{policy.key} refers to unregistered retention calculation" \
+              "#{"s" if missing.many?} #{missing.map(&:inspect).join(", ")}. Register every name " \
+              "with `config.calculate_retention_time_for` so disposition never waits forever on " \
+              "a typo."
+      end
+
+      def validate_authority_adapter!(policy)
+        rule = policy.authority_rule
+        return unless rule
+        return if rule.adapter_name == "host"
+        return if Clickwrap.config.represented_party_authority_adapter(rule.adapter_name)
+
+        raise DefinitionError,
+              "Policy #{policy.key} names represented-party authority adapter " \
+              "#{rule.adapter_name.inspect}, but it is not registered."
+      end
+
+      def validate_ip_geolocation_resolver!(policy)
+        request_evidence = policy.request_evidence
+        return unless request_evidence.records_ip_geolocation?
+        return if Clickwrap.config.ip_geolocation_resolver_for(
+          request_evidence.ip_geolocation_resolver_name
+        )
+
+        raise DefinitionError,
+              "Policy #{policy.key} names IP-geolocation resolver " \
+              "#{request_evidence.ip_geolocation_resolver_name.inspect}, but it is not configured."
+      end
+    end
+  end
+end

data/lib/clickwrap/statement.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # One act inside a policy: a single thing the person is asked to do, with the
+  # lifecycle its kind actually needs.
+  #
+  # A policy can contain several statements — "agree to the Terms" and
+  # "acknowledge the Privacy Notice" typically appear on the same screen. They
+  # produce one event and one receipt, but they never collapse into one
+  # meaning: each statement keeps its own kind, documents, assertion, answer,
+  # and lifecycle. That distinction is the whole point of the six kinds, and
+  # flattening it is exactly the mistake this gem exists to stop.
+  class Statement
+    attr_reader :key, :kind, :ordinal, :document_keys, :assertion, :label,
+                :link_labels, :choices, :purpose_key, :withdrawal_path,
+                :valid_for, :requires, :subject_fingerprint_with,
+                :subject_fingerprint_version, :record_protected_outcome_with,
+                :protected_outcome_version, :options
+
+    def initialize(key:, kind:, ordinal:, options: {})
+      @key = key.to_s
+      @kind = kind.to_s
+      @ordinal = ordinal
+      @options = options
+
+      @document_keys = Array(options[:document]).map(&:to_s)
+      @assertion = LocalizedText.new(options[:statement])
+      @label = LocalizedText.new(options[:label])
+      @link_labels = build_link_labels(options[:link_label])
+      @choices = normalize_choices(options[:choices])
+      @purpose_key = (options[:purpose] || key).to_s
+      @withdrawal_path = options[:withdrawal_path]
+      @valid_for = options[:valid_for]
+      @requires = Array(options[:requires]).map(&:to_s)
+      @subject_fingerprint_with = options[:subject_fingerprint_with]
+      @subject_fingerprint_version = options[:subject_fingerprint_version]&.to_s
+      @record_protected_outcome_with = options[:record_protected_outcome_with]
+      @protected_outcome_version = options[:protected_outcome_version]&.to_s
+
+      validate!
+      freeze
+    end
+
+    # Optional statements are offered but never required. Leaving an optional
+    # consent control unselected creates no grant at all — silence is not a
+    # refusal, and the receipt says the option was offered and not taken rather
+    # than recording a decision the person did not make.
+    def optional? = options.fetch(:optional, false) == true
+    def required? = !optional?
+
+    # A statement that must be answered one way or the other, with real
+    # unselected controls for each choice. Use it when the application needs a
+    # recorded decision rather than the absence of one.
+    def requires_an_explicit_choice? = options.fetch(:require_an_explicit_choice, false) == true
+
+    def one_time? = options.fetch(:one_time, false) == true
+
+    # When true, evidence against an older published version no longer
+    # satisfies this statement. The application decides which change is
+    # material; Clickwrap only enforces the rule it is given.
+    def requires_current_version? = options.fetch(:require_current_version, false) == true
+
+    def subject_bound? = !subject_fingerprint_with.nil?
+    def initial_action = Vocabulary.initial_action_for(kind)
+    def withdrawable? = Vocabulary.withdrawable?(kind)
+    def expirable? = Vocabulary.expirable?(kind)
+    def correctable? = Vocabulary.correctable?(kind)
+
+    def expires_after(from)
+      return nil unless valid_for
+
+      from + valid_for
+    end
+
+    # Resolves every human-facing string for one locale. Called when the
+    # presentation is built; the resolved text is what gets stored.
+    def resolve_copy(locale:)
+      {
+        "assertion" => assertion.resolve(locale:).first,
+        "label" => label.resolve(locale:).first,
+        "link_labels" => link_labels.transform_values { |text| text.resolve(locale:).first }
+      }
+    end
+
+    def to_snapshot
+      {
+        "key" => key,
+        "kind" => kind,
+        "ordinal" => ordinal,
+        "documents" => document_keys,
+        "assertion" => assertion.to_snapshot,
+        "label" => label.to_snapshot,
+        "link_labels" => link_labels.transform_values(&:to_snapshot),
+        "choices" => choices,
+        "required" => required?,
+        "optional" => optional?,
+        "requires_an_explicit_choice" => requires_an_explicit_choice?,
+        "requires_current_version" => requires_current_version?,
+        "one_time" => one_time?,
+        "purpose_key" => purpose_key,
+        "withdrawal_path" => withdrawal_path,
+        "valid_for_seconds" => valid_for&.to_i,
+        "requires" => requires,
+        "subject_fingerprint_with" => subject_fingerprint_with ? "configured" : nil,
+        "subject_fingerprint_version" => subject_fingerprint_version,
+        "record_protected_outcome_with" => record_protected_outcome_with ? "configured" : nil,
+        "protected_outcome_version" => protected_outcome_version
+      }.compact
+    end
+
+    private
+
+    def build_link_labels(declaration)
+      case declaration
+      when nil then {}
+      when String, Symbol then { document_keys.first.to_s => LocalizedText.new(declaration) }
+      when Hash then declaration.to_h { |key, value| [key.to_s, LocalizedText.new(value)] }
+      else
+        raise DefinitionError,
+              "`link_label:` on statement #{key} must be text or a hash of document key to text"
+      end
+    end
+
+    # Choices are written as { yes: :grant, no: :decline } so the policy states
+    # both what the person can pick and what each pick means. A choice whose
+    # meaning is not one of the kind's actions would produce an event action
+    # nothing downstream can interpret.
+    def normalize_choices(declaration)
+      return nil if declaration.nil?
+
+      unless declaration.is_a?(Hash)
+        raise DefinitionError,
+              "`choices:` on statement #{key} must be a hash of choice name to meaning, " \
+              "for example { yes: :grant, no: :decline }"
+      end
+
+      declaration.to_h { |choice, meaning| [choice.to_s, meaning.to_s] }.freeze
+    end
+
+    def validate!
+      unless Vocabulary.kind?(kind)
+        raise DefinitionError, "#{kind.inspect} is not one of: #{Vocabulary::KINDS.join(", ")}"
+      end
+
+      validate_assertion!
+      validate_lifecycle!
+      validate_versioned_callbacks!
+      validate_choices!
+      validate_consent!
+    end
+
+    def validate_assertion!
+      return if assertion.present?
+
+      raise DefinitionError,
+            "Statement #{key} has no assertion text. Give it `statement:` with the exact " \
+            "first-person sentence the server should include in its offer, because that is what " \
+            "the receipt records."
+    end
+
+    def validate_lifecycle!
+      if valid_for && !expirable?
+        raise DefinitionError,
+              "Statement #{key} is #{kind}, which does not expire, but it declares " \
+              "`valid_for:`. Agreements and attestations are superseded by new versions or " \
+              "corrections instead."
+      end
+
+      if one_time? && !Vocabulary.one_time_allowed?(kind)
+        raise DefinitionError,
+              "Statement #{key} is #{kind}, but `one_time:` only makes sense for an " \
+              "authorization bound to a single protected action."
+      end
+
+      return unless Vocabulary.one_time_allowed?(kind) && one_time? && valid_for.nil?
+
+      raise DefinitionError,
+            "One-time authorization #{key} has no `valid_for:`. An authorization that never " \
+            "expires and is never consumed would stay usable indefinitely; say how long it is " \
+            "good for."
+    end
+
+    def validate_choices!
+      return if choices.nil?
+
+      # Choices belong to the initial act. Lifecycle actions such as consumed,
+      # revoked, superseded, or corrected are server-authored transitions and
+      # must never become meanings a browser can choose in a capture.
+      permitted = [initial_action]
+      permitted.push("grant", "decline") if kind == "consent"
+      unknown = choices.values.reject { |meaning| permitted.include?(meaning) }
+      return if unknown.empty?
+
+      raise DefinitionError,
+            "Statement #{key} maps a choice to #{unknown.join(", ")}, which is not something a " \
+            "#{kind} can record. Use one of: #{permitted.uniq.join(", ")}."
+    end
+
+    # Proc bodies cannot be serialized into a frozen policy revision. Requiring
+    # a human-chosen version makes a behavior change visible in the revision
+    # digest and lets capture reject an old presentation whose executable
+    # callback no longer exists under the same meaning.
+    def validate_versioned_callbacks!
+      if subject_fingerprint_with && !subject_fingerprint_with.respond_to?(:call)
+        raise DefinitionError,
+              "Statement #{key} gives `subject_fingerprint_with:` a " \
+              "#{subject_fingerprint_with.class}; it must be callable."
+      end
+
+      if subject_fingerprint_with && subject_fingerprint_version.to_s.strip.empty?
+        raise DefinitionError,
+              "Statement #{key} configures `subject_fingerprint_with:` but gives no " \
+              "`subject_fingerprint_version:`. Name the callback contract (for example " \
+              '"covered-orders-v1") and change that name whenever its behavior changes.'
+      end
+
+      if record_protected_outcome_with && !record_protected_outcome_with.respond_to?(:call)
+        raise DefinitionError,
+              "Statement #{key} gives `record_protected_outcome_with:` a " \
+              "#{record_protected_outcome_with.class}; it must be callable."
+      end
+
+      return unless record_protected_outcome_with && protected_outcome_version.to_s.strip.empty?
+
+      raise DefinitionError,
+            "Statement #{key} configures `record_protected_outcome_with:` but gives no " \
+            "`protected_outcome_version:`. Name the callback contract and change that name " \
+            "whenever the recorded outcome shape or meaning changes."
+    end
+
+    def validate_consent!
+      return unless kind == "consent"
+
+      if withdrawal_path.nil?
+        raise DefinitionError,
+              "Consent statement #{key} has no `withdrawal_path:`. Consent that cannot be " \
+              "withdrawn as easily as it was given is not something Clickwrap will record as " \
+              "consent. Point it at the page where someone can change their mind."
+      end
+
+      return unless requires_an_explicit_choice? && choices.nil?
+
+      raise DefinitionError,
+            "Consent statement #{key} requires an explicit choice but declares no `choices:`. " \
+            "Give it the options the person will actually see."
+    end
+  end
+end

data/lib/clickwrap/subject_fingerprint.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # One implementation of the aggregate subject fingerprint used by
+  # presentation, remediation, capture, and verification. A security binding
+  # implemented four nearly-identical ways eventually becomes four different
+  # bindings; this is deliberately the only path.
+  module SubjectFingerprint
+    module_function
+
+    def for(policy, subject)
+      fingerprints = policy.statements.filter_map do |statement|
+        next unless statement.subject_bound?
+
+        [statement.key, for_statement(statement, subject)]
+      end.to_h
+
+      fingerprints.empty? ? nil : Digest.digest_canonical(fingerprints)
+    end
+
+    def for_statement(statement, subject)
+      return nil if subject.nil?
+
+      value = statement.subject_fingerprint_with.call(subject)
+      value.nil? ? nil : Digest.digest(value.to_s)
+    end
+  end
+end

data/lib/clickwrap/submission.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # What came back from the browser: a signed presentation token and the
+  # answers to the statements that token declared.
+  #
+  # Nothing else. A submission cannot carry a policy key, a document version, a
+  # validity date, a retention rule, a subject, an IP address, a user-agent, or
+  # a geolocation, because every one of those is a decision the server makes and
+  # a form field is not a safe place to keep one. Unknown keys are rejected
+  # rather than ignored, so an attempt to smuggle one in fails loudly instead of
+  # silently doing nothing and looking like it worked.
+  class Submission
+    ENVELOPE_KEY = :clickwrap_submission
+    ENVELOPE_KEYS = %w[presentation_token answers].freeze
+
+    # Names a client must never be able to set. They exist as a check rather
+    # than a filter: a request containing one is a request worth failing.
+    REFUSED_KEYS = %w[
+      policy policy_key policy_revision revision document document_version version
+      valid_from valid_until expires_at retention retain_until subject subject_id
+      actor actor_id tenant ip_address remote_ip browser_user_agent user_agent
+      ip_geolocation geolocation latitude longitude resolver recorded_at
+      server_observed_ip_address capture_channel authentication_method
+    ].freeze
+
+    # The longest an answer can be: generous for any declared choice name,
+    # far too short for smuggled prose or a payload.
+    MAX_ANSWER_LENGTH = 120
+
+    attr_reader :presentation_token, :answers
+
+    def initialize(presentation_token:, answers: {})
+      @presentation_token = presentation_token
+      @answers = normalize_answers(answers)
+      freeze
+    end
+
+    class << self
+      # Reads the generated envelope out of controller params.
+      def from_params(params, key: ENVELOPE_KEY)
+        envelope = extract_envelope(params, key)
+
+        raise SubmissionInvalid, missing_envelope_message(key) if envelope.nil?
+
+        new(
+          presentation_token: envelope["presentation_token"] || envelope[:presentation_token],
+          answers: envelope["answers"] || envelope[:answers] || {}
+        )
+      end
+
+      def missing_envelope_message(key)
+        "The request contains no #{key} parameter. The form helper renders it; a custom form " \
+          "must include the signed presentation token from Clickwrap.present."
+      end
+
+      private
+
+      def extract_envelope(params, key)
+        envelope = params[key] || params[key.to_s]
+        return nil if envelope.nil?
+
+        raw = if envelope.respond_to?(:to_unsafe_h)
+                # This is an evidence/security parser, not a mass-assignment
+                # boundary. `permit` would silently erase unknown fields before
+                # we could refuse them, making a forged server-owned field look
+                # as though it worked. Read the envelope, validate its complete
+                # shape below, and only then select the two values we understand.
+                envelope.to_unsafe_h
+              elsif envelope.is_a?(Hash)
+                envelope.to_h
+              end
+
+        unless raw
+          raise SubmissionInvalid,
+                "The #{key} parameter must be an object containing a presentation_token and " \
+                "an answers object. It was #{envelope.class}; Clickwrap did not try to guess " \
+                "how to reinterpret it."
+        end
+
+        normalized_keys = raw.keys.map(&:to_s)
+        duplicate_keys = normalized_keys.tally.select { |_, count| count > 1 }.keys
+        unknown_keys = normalized_keys.uniq - ENVELOPE_KEYS
+        if duplicate_keys.any? || unknown_keys.any?
+          problems = []
+          problems << "duplicate keys #{duplicate_keys.join(", ")}" if duplicate_keys.any?
+          problems << "unknown keys #{unknown_keys.join(", ")}" if unknown_keys.any?
+          raise SubmissionInvalid,
+                "The #{key} envelope contains #{problems.join(" and ")}. It may contain only " \
+                "presentation_token and answers; policy, authority, identity, retention, and " \
+                "request-evidence decisions are server-owned."
+        end
+
+        raw
+      end
+    end
+
+    # Deliberately not memoized: a Submission is frozen the moment it is built,
+    # so an instance variable written on first use would raise. Verifying the
+    # token again costs one signature check, which is a small price for an
+    # object that cannot be tampered with after construction.
+    def manifest
+      PresentationManifest.from_token(presentation_token)
+    end
+
+    def answer_for(statement_key) = answers[statement_key.to_s]
+
+    def answered?(statement_key)
+      self.class.affirmative?(answer_for(statement_key))
+    end
+
+    def self.affirmative?(value)
+      return false if value.nil?
+
+      !%w[0 false off no].include?(value.to_s.downcase) && value.to_s != ""
+    end
+
+    def to_h
+      { "presentation_token" => presentation_token, "answers" => answers }
+    end
+
+    private
+
+    # Answers are scalars keyed by statement. A nested structure would be a way
+    # to smuggle something structured past a check that expected a checkbox.
+    def normalize_answers(raw)
+      hash = if raw.respond_to?(:to_unsafe_h)
+               raw.to_unsafe_h
+             elsif raw.is_a?(Hash)
+               raw.to_h
+             else
+               raise SubmissionInvalid,
+                     "The clickwrap answers parameter must be an object keyed by statement. It " \
+                     "was #{raw.class}; each answer must be a single checkbox state or declared choice."
+             end
+
+      hash.to_h do |key, value|
+        name = key.to_s
+
+        if REFUSED_KEYS.include?(name)
+          raise SubmissionInvalid,
+                "The submitted answers include #{name.inspect}, which is a server-owned " \
+                "decision. Clickwrap resolves the policy, document versions, validity, subject, " \
+                "retention, and request evidence itself; a browser cannot choose any of them."
+        end
+
+        unless value.is_a?(String) || value.is_a?(Symbol) || [true, false, nil].include?(value) ||
+               value.is_a?(Numeric)
+          raise SubmissionInvalid,
+                "The answer for #{name.inspect} is a #{value.class}. Answers are single values: " \
+                "a checkbox state or the name of one declared choice."
+        end
+
+        # Answers are the one client-authored value that becomes digested
+        # evidence, so their domain is bounded: a checkbox state or a declared
+        # choice name is never longer than this. Refused, never truncated —
+        # evidence is recorded exactly or not at all.
+        if value.to_s.length > MAX_ANSWER_LENGTH
+          raise SubmissionInvalid,
+                "The answer for #{name.inspect} is #{value.to_s.length} characters. An answer " \
+                "is a checkbox state or the name of one declared choice, never free text; " \
+                "anything over #{MAX_ANSWER_LENGTH} characters is refused rather than recorded."
+        end
+
+        [name, value.nil? ? nil : value.to_s]
+      end.freeze
+    end
+  end
+end

data/lib/clickwrap/system_actor.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # A named non-human actor, for seeds, imports, migrations, and background
+  # processes. Recording one is how a system-created record says out loud that
+  # no person did this, instead of leaving a gap that later reads like a human
+  # action nobody can find.
+  class SystemActor
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_s
+
+      if @name.strip.empty?
+        raise ArgumentError,
+              "A system actor needs a name describing what created the record, for example " \
+              "\"database_seed\" or \"crm_import_2026_08\"."
+      end
+
+      freeze
+    end
+
+    def clickwrap_actor_reference = "system/#{name}"
+    def id = name
+    def to_s = clickwrap_actor_reference
+    def persisted? = false
+    def ==(other) = other.is_a?(self.class) && other.name == name
+    alias eql? ==
+    def hash = [self.class, name].hash
+  end
+end