clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/view_helpers.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # View helpers for CUSTOM presentation surfaces — the middle ground between
+  # `form.clickwrap` (the one-line happy path) and hand-writing every input
+  # against `Clickwrap.present` primitives.
+  #
+  # A custom surface has to render three things correctly or its captures
+  # silently fail at submit: the signed token under the exact envelope name,
+  # each control under its statement's declared name and id, and a call to
+  # action whose words match the ones the manifest recorded. These helpers own
+  # those three contracts; the host owns every class, wrapper, and data
+  # attribute around them.
+  #
+  #   <% preparation = Clickwrap.present(:withdrawal_preparation, actor: current_user,
+  #                                      submit_button_text: "He leído todo") %>
+  #   <%= clickwrap_presentation_token_field(preparation) %>
+  #   <% preparation.statements.each do |statement| %>
+  #     <%= clickwrap_statement_check_box(statement, class: "my-checkbox") %>
+  #     <%= label_tag statement.control_id, statement.assertion %>
+  #   <% end %>
+  #   <%= clickwrap_submit_button(preparation, class: "my-button") %>
+  module ViewHelpers
+    # Host-specific navigation attributes for immutable document links. This
+    # helper deliberately lives with the helpers installed into every host
+    # view, rather than only in EngineHelper: `form.clickwrap` renders the
+    # engine's statement partial inside the host form's view context.
+    #
+    # The immutable href is evidence-critical and therefore cannot be
+    # overridden here. Hosts may only choose how their client opens it (for
+    # example, target: "_blank" or data: { turbo: false }).
+    #
+    # The hook is evaluated IN the rendering view, so a host can answer
+    # per-request questions the way it always does — `hotwire_native_app?`
+    # being the canonical one: a native WebView usually wants a same-window
+    # link its screen rules can route, while the web wants a new tab.
+    #
+    # `config.hotwire_native_document_links`, when set, answers native renders
+    # entirely (the attributes here, and the absolutized href in
+    # ControllerHelpers#clickwrap_document_version_path_for_presentation);
+    # the hook keeps answering everything else.
+    def clickwrap_document_link_html_options(document = nil)
+      native_options = clickwrap_hotwire_native_link_options
+      return native_options if native_options
+
+      raw_options = instance_exec(document, &Clickwrap.config.document_link_html_options_with)
+      unless raw_options.is_a?(Hash) || raw_options.is_a?(ActiveSupport::HashWithIndifferentAccess)
+        raise ConfigurationError,
+              "document_link_html_options_with must return a Hash of HTML attributes."
+      end
+
+      options = raw_options.to_h.symbolize_keys
+      # Case-insensitive on purpose: HTML lowercases attribute names and keeps
+      # the FIRST duplicate, so a smuggled "HREF" would win over the signed
+      # immutable path in the rendered link.
+      if options.keys.any? { |key| key.to_s.casecmp?("href") }
+        raise ConfigurationError,
+              "document_link_html_options_with cannot set href. Clickwrap signs the exact " \
+              "immutable document path into the presentation manifest; this hook may only " \
+              "choose how the client opens that path."
+      end
+
+      options
+    end
+
+    # The declared native answer, or nil when this render is not one of the
+    # cases `config.hotwire_native_document_links` decides.
+    def clickwrap_hotwire_native_link_options
+      native_links = Clickwrap.config.hotwire_native_document_links
+      return nil unless native_links
+      return nil unless respond_to?(:hotwire_native_app?) && hotwire_native_app?
+
+      # Asked with the CONTROLLER, not the view: the href was resolved from the
+      # controller when the presentation was signed, and the two halves of one
+      # document link must not be able to answer differently.
+      case Clickwrap.config.hotwire_native_document_link_mode(clickwrap_native_link_context)
+      when :external_browser
+        # `data-turbo-false` keeps the tap out of the Turbo/Hotwire Native
+        # navigation stack so the absolutized href reaches the system browser.
+        { target: "_blank", rel: "noopener", data: { turbo: false } }
+      when :same_screen
+        # A plain link, on purpose: the app's own native path configuration
+        # decides how the document presents (typically a modal sheet).
+        {}
+      end
+    end
+
+    def clickwrap_native_link_context
+      (controller if respond_to?(:controller)) || self
+    end
+
+    # The words that go in one control's label: a statement's own first-person
+    # assertion, or — when the control is the composed line — the whole
+    # sentence with its document links rendered inside it.
+    #
+    # One helper for both is what lets the reference statement partial render
+    # either without knowing which it has, and what makes a host's ejected
+    # partial style the composed line for free.
+    def clickwrap_statement_label(control)
+      return clickwrap_combined_sentence(control) if control.is_a?(Clickwrap::Presenter::Combined)
+
+      control.assertion
+    end
+
+    # The composed one-line offer, as markup: the sentence the presentation
+    # signed, with each document rendered as a real link where the words for it
+    # go. This is what the single checkbox's label contains, and it is a helper
+    # rather than template soup because an ejected view should be able to
+    # restyle the line without reassembling a sentence out of translated parts.
+    #
+    #   <%= label_tag presentation.combined.control_id,
+    #         clickwrap_combined_sentence(presentation.combined) %>
+    #
+    # Nothing here interpolates markup into translated text: the presenter
+    # already split every fragment around the place its documents go, so this
+    # only joins pieces that are individually safe.
+    def clickwrap_combined_sentence(combined)
+      fragments = combined.fragments.map { |fragment| clickwrap_sentence_fragment(fragment) }
+
+      safe_join([safe_join(fragments, combined.joiner), combined.terminator])
+    end
+
+    # One statement's share of that sentence.
+    def clickwrap_sentence_fragment(fragment)
+      links = fragment.documents.map { |document| clickwrap_document_link(document) }
+
+      safe_join([fragment.prefix, safe_join(links, fragment.documents_joiner), fragment.suffix])
+    end
+
+    # One document, as the link a person presses to read it. The href is the
+    # exact path signed into the manifest and cannot be overridden here; the
+    # host's navigation hook chooses only how its client opens it. There is no
+    # "unavailable document" branch, because there is no such document: a
+    # presentation whose path could not be resolved refuses to be built at all.
+    #
+    # The "(opens in a new tab)" truth is kept and the clutter is not: it is
+    # rendered for screen readers only, and only when the link really does open
+    # a new tab — a same-window link announcing otherwise would be the page
+    # lying about itself.
+    def clickwrap_document_link(document)
+      options = clickwrap_document_link_html_options(document)
+      link = link_to(document.label, document.path, class: "clickwrap-documents__link", **options)
+      return link unless options[:target].to_s == "_blank"
+
+      # The separating space lives INSIDE the sr-only span, which is out of
+      # flow: a space between the elements would be laid out, and the sentence
+      # would read "…Privacy Policy ." with a gap before its own full stop.
+      hint = tag.span(" #{t("clickwrap.ui.opens_in_new_tab")}", class: "clickwrap-sr-only")
+      safe_join([link, hint])
+    end
+
+    # The signed presentation token, under the envelope name the capture reads.
+    # This is the one hidden field a clickwrap form carries — and the one whose
+    # name must never be hand-typed, because a typo here is a form that looks
+    # complete and refuses every submission.
+    def clickwrap_presentation_token_field(presentation)
+      hidden_field_tag "clickwrap_submission[presentation_token]", presentation.token, id: nil
+    end
+
+    # One statement's checkbox: declared name and id, initially unchecked
+    # (always — a pre-ticked box records the page's default, not the person's
+    # action), `required` mirroring the server's own rule as progressive
+    # enhancement. Everything in `**options` is yours; pass `checked: true`
+    # only when re-rendering a submission the person already made.
+    def clickwrap_statement_check_box(statement, checked: false, **options)
+      options = { id: statement.control_id }.merge(options)
+      options[:required] = true if statement.required? && !options.key?(:required)
+
+      check_box_tag statement.control_name, "1", checked, options
+    end
+
+    # One option of a statement rendered as a radio group — the pattern for an
+    # answer with more than one presented choice (or an affirmative/negative
+    # pair, where the negative submits "0"). All options share the statement's
+    # control name; each gets a value-suffixed id for its label.
+    def clickwrap_statement_radio_button(statement, value, checked: false, **options)
+      options = { id: "#{statement.control_id}_#{value}" }.merge(options)
+
+      radio_button_tag statement.control_name, value, checked, options
+    end
+
+    # The call to action, worded by the presentation itself. The manifest
+    # recorded `submit_button_text` when the offer was signed; rendering the
+    # button from the same object is what makes drift between the recorded
+    # words and the pressed words impossible on a custom surface.
+    def clickwrap_submit_button(presentation, **)
+      submit_tag(presentation.submit_button_text, **)
+    end
+  end
+end

data/lib/clickwrap/vocabulary.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # Every stable string Clickwrap writes into evidence lives here, frozen, in
+  # one place. Historical receipts are read by code that may be years newer
+  # than the code that wrote them, so these values are part of the public
+  # compatibility promise: they are added to, never renamed or repurposed.
+  #
+  # This taxonomy is product design. It is not a statutory vocabulary, and
+  # naming an act `agreement` or `consent` does not determine its legal effect.
+  module Vocabulary
+    # The six kinds, each with the lifecycle it actually needs.
+    KINDS = %w[
+      agreement
+      acknowledgment
+      consent
+      declaration
+      attestation
+      authorization
+    ].freeze
+
+    # The policy DSL verb that declares each kind.
+    VERB_FOR_KIND = {
+      "agreement" => "agree_to",
+      "acknowledgment" => "acknowledge",
+      "consent" => "consent_to",
+      "declaration" => "declare",
+      "attestation" => "attest",
+      "authorization" => "authorize"
+    }.freeze
+
+    KIND_FOR_VERB = VERB_FOR_KIND.invert.freeze
+
+    # The action recorded when a statement is first captured.
+    INITIAL_ACTION_FOR_KIND = {
+      "agreement" => "agreed",
+      "acknowledgment" => "acknowledged",
+      "consent" => "granted",
+      "declaration" => "declared",
+      "attestation" => "attested",
+      "authorization" => "authorized"
+    }.freeze
+
+    # Every action a statement of each kind may ever record.
+    ACTIONS_FOR_KIND = {
+      "agreement" => %w[agreed superseded].freeze,
+      "acknowledgment" => %w[acknowledged superseded expired].freeze,
+      "consent" => %w[granted declined withdrawn renewed scope_changed].freeze,
+      "declaration" => %w[declared corrected superseded expired].freeze,
+      "attestation" => %w[attested corrected superseded].freeze,
+      "authorization" => %w[authorized consumed expired revoked].freeze
+    }.freeze
+
+    ACTIONS = ACTIONS_FOR_KIND.values.flatten.uniq.freeze
+
+    # Kinds whose meaning includes a withdrawal route. Withdrawing future
+    # consent never rewrites a historical agreement or factual declaration, so
+    # only `consent` is withdrawable.
+    WITHDRAWABLE_KINDS = %w[consent].freeze
+
+    # Kinds that may carry a validity period.
+    EXPIRABLE_KINDS = %w[acknowledgment consent declaration authorization].freeze
+
+    # Kinds that may be corrected by the same actor without implying the
+    # original statement was false when it was made.
+    CORRECTABLE_KINDS = %w[declaration attestation].freeze
+
+    # Kinds that may be scoped to a single protected action.
+    ONE_TIME_KINDS = %w[authorization].freeze
+
+    # What produced an event. `capture` is a human action recorded by this
+    # application; every other value says plainly that something else happened.
+    EVENT_TYPES = %w[
+      capture
+      withdrawal
+      correction
+      supersession
+      expiry
+      consumption
+      revocation
+      renewal
+      scope_change
+      exemption
+      imported_legacy
+      external_receipt
+      disposition
+      legal_hold_placed
+      legal_hold_released
+      receipt_access
+      provider_outcome
+    ].freeze
+
+    # Event types that record an act by a human through a Clickwrap
+    # presentation. These satisfy `agreed_to?`, `consented_to?` and the other
+    # human-action predicates — as does `imported_legacy`, which carries what a
+    # previous system recorded about a human action (an exemption never does:
+    # it records that no human acted).
+    HUMAN_ACTION_EVENT_TYPES = %w[capture correction renewal scope_change].freeze
+
+    # What belongs in an actor's own receipts collection: every act they
+    # performed here, plus their history imported from a previous system or
+    # recorded by an external provider. A migrated user's records screen must
+    # show their history, not an empty list that implies they never agreed to
+    # anything.
+    ACTOR_RECEIPT_EVENT_TYPES = (HUMAN_ACTION_EVENT_TYPES + %w[imported_legacy external_receipt]).freeze
+
+    # Where a capture came from. This is recorded, never guessed: a missing
+    # browser parameter is not evidence of a system actor.
+    CAPTURE_CHANNELS = %w[
+      web_browser
+      native_app
+      api_client
+      operator
+      background_job
+      imported_provider
+      system
+    ].freeze
+
+    # The current state of one statement for one actor/subject, projected from
+    # retained event payloads.
+    STATES = %w[
+      active
+      declined
+      withdrawn
+      expired
+      superseded
+      consumed
+      revoked
+      corrected
+      exempted
+    ].freeze
+
+    # A statement in one of these states cannot satisfy a requirement.
+    INACTIVE_STATES = %w[declined withdrawn expired superseded consumed revoked corrected].freeze
+
+    # How a receipt describes each optional request-evidence field. "Blank" is
+    # never allowed to blur "we chose not to collect this" into "collection
+    # failed" or "we deleted it".
+    REQUEST_EVIDENCE_STATES = %w[
+      not_configured
+      unavailable
+      recorded
+      redacted_for_this_viewer
+      deleted_after_retention
+      held
+    ].freeze
+
+    # Every IP-geolocation data field a policy can enable individually.
+    # `latitude_and_longitude` is one coupled choice on purpose: half a
+    # coordinate is not a result.
+    IP_GEOLOCATION_DATA_FIELDS = %w[
+      country
+      region
+      city
+      postal_code
+      latitude_and_longitude
+      timezone
+      continent
+      metro_code
+      accuracy_radius_in_kilometers
+    ].freeze
+
+    # Provenance that travels with any stored IP-geolocation result. A policy
+    # cannot keep provider-derived coordinates while stripping the uncertainty
+    # needed to interpret them.
+    IP_GEOLOCATION_PROVENANCE_FIELDS = %w[
+      ip_geolocation_provider_name
+      ip_geolocation_provider_source
+      ip_geolocation_database_version
+      ip_geolocation_database_sha256
+      ip_geolocation_accuracy_radius_confidence_percentage
+      ip_geolocation_was_estimated
+      ip_geolocation_source_was_verified_by_host
+      ip_geolocation_resolved_at
+      ip_geolocation_unavailable_reason
+    ].freeze
+
+    # How the actor was attributed to the event. None of these is an identity
+    # claim; they say which application-supplied context was recorded.
+    ATTRIBUTION_METHODS = %w[
+      authenticated_session
+      account_registration
+      public_form
+      operator_session
+      api_credential
+      anonymous_identifier
+      system_process
+      imported_provider
+      unknown
+    ].freeze
+
+    # Stable machine-readable reasons a verification can fail. Applications
+    # branch on these symbols; the human message is localized separately.
+    VERIFICATION_ERRORS = %i[
+      no_evidence
+      wrong_actor
+      wrong_tenant
+      wrong_subject
+      subject_fingerprint_mismatch
+      stale_policy_revision
+      unseen_document_version
+      missing_answer
+      declined
+      declaration_expired
+      acknowledgment_expired
+      consent_withdrawn
+      superseded
+      revoked
+      authorization_consumed
+      authorization_expired
+      predecessor_missing
+      wrong_order
+      replay_rejected
+      presentation_expired
+      presentation_invalid
+      presentation_actor_mismatch
+      presentation_subject_mismatch
+      presentation_tenant_mismatch
+      presentation_channel_mismatch
+      presentation_policy_mismatch
+      represented_party_mismatch
+      represented_party_authority_mismatch
+      represented_party_creation_flow_mismatch
+      registration_flow_mismatch
+      registration_actor_type_mismatch
+      document_digest_mismatch
+      integrity_check_failed
+      exemption_not_accepted
+      request_evidence_unavailable
+      core_event_disposed
+      unknown_policy
+      unknown_statement
+    ].freeze
+
+    # Which assurance tier a verification result was produced under. Each tier
+    # states exactly what it detects and nothing more.
+    INTEGRITY_TIERS = %w[
+      baseline
+      database_hardening
+      chained_history
+      external_event_anchoring
+      third_party_timestamp
+    ].freeze
+
+    # Public words that would overclaim what any of this proves. The release
+    # test greps generated output, receipts, task output, and documentation for
+    # these.
+    PROHIBITED_CLAIM_PHRASES = [
+      "gdpr compliant",
+      "gdpr-compliant",
+      "legally compliant",
+      "compliance guaranteed",
+      "court proof",
+      "court-proof",
+      "tamper proof",
+      "tamper-proof",
+      "legally binding",
+      "guarantees enforceability",
+      "audit guaranteed",
+      "qualified electronic signature",
+      "trusted time",
+      "trusted_timestamp",
+      "verified identity",
+      "legal advice"
+    ].freeze
+
+    class << self
+      def kind?(value) = KINDS.include?(value.to_s)
+      def action?(value) = ACTIONS.include?(value.to_s)
+      def event_type?(value) = EVENT_TYPES.include?(value.to_s)
+      def capture_channel?(value) = CAPTURE_CHANNELS.include?(value.to_s)
+      def state?(value) = STATES.include?(value.to_s)
+
+      def actions_for(kind)
+        ACTIONS_FOR_KIND.fetch(kind.to_s) do
+          raise UnknownStatementError, "#{kind.inspect} is not one of: #{KINDS.join(", ")}"
+        end
+      end
+
+      def initial_action_for(kind)
+        INITIAL_ACTION_FOR_KIND.fetch(kind.to_s) do
+          raise UnknownStatementError, "#{kind.inspect} is not one of: #{KINDS.join(", ")}"
+        end
+      end
+
+      def withdrawable?(kind) = WITHDRAWABLE_KINDS.include?(kind.to_s)
+      def expirable?(kind) = EXPIRABLE_KINDS.include?(kind.to_s)
+      def correctable?(kind) = CORRECTABLE_KINDS.include?(kind.to_s)
+      def one_time_allowed?(kind) = ONE_TIME_KINDS.include?(kind.to_s)
+      def human_action_event_type?(value) = HUMAN_ACTION_EVENT_TYPES.include?(value.to_s)
+      def inactive_state?(value) = INACTIVE_STATES.include?(value.to_s)
+    end
+  end
+end