clickwrap 0.0.0 → 0.1.0

data/app/controllers/clickwrap/receipts_controller.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # "Show me exactly what the application recorded."
+  #
+  # Every screen here answers that question about one recorded event, and every
+  # screen here goes through the host's authorization callback to do it. There
+  # is no built-in "actors can always read their own" shortcut: the host decides
+  # who may read what, and the conventional initializer says so out loud.
+  #
+  #   config.authorize_receipt_access_with = lambda do |controller, receipt|
+  #     controller.current_user.present? &&
+  #       (controller.current_user == receipt.actor || controller.current_user.admin?)
+  #   end
+  #
+  # Until that is configured the default answers false, so an unconfigured host
+  # shows an empty list rather than leaking a receipt it never decided to share.
+  # A receipt the viewer may not see is NOT FOUND, never forbidden: a 403 tells
+  # an outsider that the id they guessed exists, and existence is itself
+  # information about someone.
+  class ReceiptsController < ApplicationController
+    before_action :require_clickwrap_actor
+
+    # An honest page size rather than an unbounded query. A production actor can
+    # accumulate years of retained history even when optional annex data is
+    # disposed on a separate schedule.
+    PER_PAGE = 50
+
+    # How many of the viewer's own rows this screen will read looking for
+    # PER_PAGE it may show. The host's callback is Ruby, not SQL, so the
+    # database cannot apply it and something has to bound the search. A viewer
+    # whose first thousand events are all unreadable to them is a host
+    # authorization question, not a paging question.
+    AUTHORIZATION_SCAN_LIMIT = 1_000
+
+    BATCH_SIZE = 100
+
+    def index
+      @events = authorized_page
+    end
+
+    def show
+      @event = find_readable_event
+      return head :not_found if @event.nil?
+
+      @receipt = @event.receipt
+
+      respond_to do |format|
+        format.html
+        format.json { render json: @receipt.to_canonical_json }
+      end
+    end
+
+    private
+
+    # Authorize, THEN paginate. Taking PER_PAGE rows and filtering afterwards
+    # renders an empty page whenever the viewer's newest fifty events happen to
+    # be ones the host will not show them — while readable receipts sit at row
+    # fifty-one. "Your receipts are gone" is a bad thing for this screen to say
+    # by accident.
+    #
+    # The actor is eager-loaded because the conventional callback compares
+    # `controller.current_user == receipt.actor`, which is one query per row
+    # otherwise. Reading in batches keeps that at a handful of queries for the
+    # whole page instead of one per receipt.
+    def authorized_page
+      authorized = []
+      scanned = 0
+
+      while authorized.length < page_size && scanned < authorization_scan_limit
+        batch = own_events.includes(:actor).offset(scanned).limit(batch_size).to_a
+        break if batch.empty?
+
+        authorized.concat(batch.select { |event| authorized_to_read?(event) })
+        scanned += batch.length
+        break if batch.length < batch_size
+      end
+
+      authorized.first(page_size)
+    end
+
+    # Readers rather than bare constants so a host that ejects this controller
+    # can page it differently by overriding one method.
+    def page_size = PER_PAGE
+    def batch_size = BATCH_SIZE
+    def authorization_scan_limit = AUTHORIZATION_SCAN_LIMIT
+
+    # The viewer's own events, newest first. Scoping by the actor reference the
+    # evidence itself carries — rather than by a foreign key that a deleted
+    # account would take with it — is what keeps this list working after a row
+    # has gone.
+    def own_events
+      Event.for_actor(actor_reference)
+           .order(recorded_at_by_server: :desc, id: :desc)
+    end
+
+    def actor_reference
+      Reference.actor(clickwrap_current_actor)
+    end
+
+    def find_readable_event
+      event = Event.find_by(id: params[:id])
+      return nil if event.nil?
+      return nil unless authorized_to_read?(event)
+
+      event
+    end
+
+    # The host's answer, treated as a plain yes/no. The default is no, so a host
+    # that has not made this decision yet cannot accidentally publish anything.
+    def authorized_to_read?(event)
+      !!Clickwrap.config.authorize_receipt_access_with.call(self, event.receipt)
+    end
+  end
+end

data/app/controllers/clickwrap/withdrawals_controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # Withdrawing one consent purpose.
+  #
+  # This screen is deliberately as short as the screen that granted the consent
+  # in the first place: one page, one control, one press. Withdrawal must be no
+  # harder than granting was — no support ticket, no email, no re-authentication
+  # the grant did not require, no confirmation maze. A gem that made taking
+  # consent back harder than giving it would be building the exact pattern it
+  # exists to prevent, so this controller has nothing in it but the two actions.
+  #
+  # Withdrawal APPENDS an event. It never deletes or edits the historical grant:
+  # what was true then stays recorded, and what is true now is that the person
+  # changed their mind. Only consent is withdrawable — withdrawing future
+  # processing does not rewrite a past agreement or a factual declaration.
+  class WithdrawalsController < ApplicationController
+    before_action :require_clickwrap_actor
+    before_action :find_purpose
+    before_action :remember_return_destination
+
+    def new; end
+
+    def create
+      Clickwrap.withdraw!(
+        @purpose_key,
+        actor: clickwrap_current_actor,
+        tenant: clickwrap_current_tenant,
+        http_request: request,
+        because: t("clickwrap.withdrawals.recorded_reason")
+      )
+
+      redirect_to @return_to, allow_other_host: false, notice: t("clickwrap.withdrawals.confirmed")
+    rescue AlreadyWithdrawnError
+      # Pressing the button twice is not an error worth showing a person. The
+      # purpose is withdrawn either way, which is what they asked for.
+      redirect_to @return_to, allow_other_host: false, notice: t("clickwrap.withdrawals.already_withdrawn")
+    rescue NotWithdrawableError => error
+      flash.now[:alert] = error.message
+      render :new, status: 422
+    end
+
+    private
+
+    # The purpose, not the policy: consent is purpose-specific, and a person
+    # withdrawing product updates is not withdrawing everything they ever did on
+    # the same screen.
+    def find_purpose
+      @purpose_key = params[:purpose_key].to_s
+
+      head :not_found if @purpose_key.empty?
+    end
+
+    # Browser-supplied navigation, checked the same way everywhere: a relative
+    # path on this host, or this engine's own root.
+    def remember_return_destination
+      @return_to = clickwrap_safe_return_to(params[:return_to], fallback: clickwrap_engine_routes.root_path)
+    end
+  end
+end

data/app/helpers/clickwrap/engine_helper.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # View helpers, available BOTH inside the engine's own views and in the HOST
+  # app's views (mixed into ActionView by the hook at the bottom of this file,
+  # the same pattern the chats and moderate gems use).
+  #
+  # Everything here is prefixed `clickwrap_`, because these methods land in
+  # every view in the host application and a gem has no business claiming a
+  # short name in that namespace.
+  module EngineHelper
+    # The standalone capture screen for one policy — the remediation route:
+    #
+    #   <%= link_to "Complete your declaration", clickwrap_capture_path(:contractor_declaration) %>
+    #
+    # Any extra options become query parameters, which is how a caller passes
+    # `return_to:` for a flow that should resume where it left off.
+    def clickwrap_capture_path(policy_key, **)
+      clickwrap_routes.capture_path(policy_key, **)
+    end
+
+    # A receipt, addressed by the event it belongs to. Takes a receipt, an
+    # event, or a bare event id, because all three turn up in host code.
+    def clickwrap_receipt_path(receipt, **)
+      clickwrap_routes.receipt_path(clickwrap_event_id_for(receipt), **)
+    end
+
+    # Where someone withdraws one consent purpose. Withdrawal is a first-class
+    # screen and not a buried mailto: link, because consent that cannot be
+    # withdrawn as easily as it was given is not something this gem will keep
+    # calling consent.
+    def clickwrap_withdrawal_path(purpose_key, **)
+      clickwrap_routes.withdrawal_path(purpose_key, **)
+    end
+
+    # The exact published bytes of one document version — what the presentation
+    # links to, and what an auditor reads later.
+    def clickwrap_document_version_path(version, **)
+      identifier = version.respond_to?(:id) ? version.id : version
+
+      clickwrap_routes.document_version_path(identifier, **)
+    end
+
+    # The gem's bundled stylesheet. Called from the engine's own views; hosts
+    # that eject and restyle the views simply stop including it.
+    def clickwrap_styles
+      stylesheet_link_tag "clickwrap", "data-turbo-track": "reload"
+    end
+
+    # Engine URL helpers that work from EVERY render context:
+    #
+    #   * host views: the mounted proxy (`clickwrap.`) carries the mount prefix
+    #     baked in at mount time, so URLs come out right;
+    #   * engine views during requests: the engine's controllers inherit from
+    #     the host's ApplicationController, so the proxy is available there too;
+    #   * no mount at all (bare view tests): fall back to the engine's own
+    #     url_helpers — prefix-less, but nothing better exists without a mount.
+    #
+    # NOTE: assumes the default mount name (`mount Clickwrap::Engine => "/x"`
+    # auto-names the proxy `clickwrap`). A host mounting with `as: :something`
+    # overrides this helper.
+    def clickwrap_routes
+      respond_to?(:clickwrap) ? clickwrap : Clickwrap::Engine.routes.url_helpers
+    end
+
+    # The host application's own routes, reachable from inside this isolated
+    # engine's views — where a bare `some_path` would be resolved against the
+    # engine's route set and explode.
+    def clickwrap_main_routes
+      respond_to?(:main_app) ? main_app : Rails.application.routes.url_helpers
+    end
+
+    private
+
+    def clickwrap_event_id_for(receipt)
+      return receipt.event_id if receipt.respond_to?(:event_id)
+      return receipt.id if receipt.respond_to?(:id)
+
+      receipt
+    end
+  end
+end
+
+# Expose the helpers to the HOST app's views (isolated engines don't share
+# helpers automatically). The hook lives HERE, at the bottom of the file that
+# defines the constant — not in an engine initializer — so it's self-resolving:
+# whenever this file loads (eager load, autoload on first use, or the engine's
+# to_prepare touch), the constant already exists by the time the hook can
+# possibly run. Registering it from an initializer instead would blow up at boot
+# in hosts where ActionView is already loaded during initializers (web-console
+# does this), because `include Clickwrap::EngineHelper` would fire before the
+# autoloader is ready.
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:action_view) do
+    include Clickwrap::EngineHelper
+  end
+end

data/app/views/clickwrap/captures/show.html.erb

@@ -0,0 +1,34 @@
+<%#
+  The standalone capture screen: one policy, on a page of its own.
+
+  The form posts back to the SAME URL it was served from, so a failed
+  submission re-renders here — reloadable, shareable, and in the navigation
+  context the host intended, with or without JavaScript.
+%>
+<%= clickwrap_styles %>
+
+<div class="clickwrap clickwrap-screen">
+  <header class="clickwrap-screen__header">
+    <h1 class="clickwrap-screen__title"><%= t("clickwrap.captures.title") %></h1>
+    <p class="clickwrap-screen__intro"><%= t("clickwrap.captures.intro") %></p>
+  </header>
+
+  <% if flash.now[:alert].present? || flash[:alert].present? %>
+    <p class="clickwrap-flash clickwrap-flash--alert" role="alert"><%= flash[:alert] %></p>
+  <% end %>
+
+  <%= form_with url: clickwrap_routes.capture_path(@presentation.policy_key),
+        method: :post,
+        class: "clickwrap-screen__form" do %>
+    <%= hidden_field_tag :return_to, @return_to, id: nil %>
+    <% if @remediation_token.present? %>
+      <%= hidden_field_tag :remediation_token, @remediation_token, id: nil %>
+    <% end %>
+
+    <%= render "clickwrap/shared/fields",
+          presentation: @presentation,
+          errors: clickwrap_errors,
+          submit: { text: @presentation.submit_button_text, options: {} },
+          wrapper_options: {} %>
+  <% end %>
+</div>

data/app/views/clickwrap/receipts/index.html.erb

@@ -0,0 +1,38 @@
+<%#
+  The viewer's own receipts, newest first.
+
+  Every row here passed the host's `authorize_receipt_access_with` callback. An
+  unconfigured host sees an empty list, which is the safe direction to be wrong
+  in: a receipt is only shown once somebody decided it should be.
+%>
+<%= clickwrap_styles %>
+
+<div class="clickwrap clickwrap-screen">
+  <header class="clickwrap-screen__header">
+    <h1 class="clickwrap-screen__title"><%= t("clickwrap.receipts.index_title") %></h1>
+  </header>
+
+  <% if @events.any? %>
+    <ul class="clickwrap-receipts">
+      <% @events.each do |event| %>
+        <li class="clickwrap-receipts__item">
+          <a class="clickwrap-receipts__link" href="<%= clickwrap_receipt_path(event.id) %>">
+            <%= event.policy_key %>
+          </a>
+          <%# Deliberately a plain UTC timestamp rather than `l()`: many hosts do
+              not bundle rails-i18n, and a time recorded by a server is clearest
+              when it is displayed without a silent timezone conversion. %>
+          <span class="clickwrap-receipts__meta">
+            <%= t("clickwrap.receipts.recorded_at_by_server") %>
+            <%= event.recorded_at_by_server&.utc&.strftime("%Y-%m-%d %H:%M UTC") %>
+          </span>
+          <span class="clickwrap-receipts__meta">
+            <%= t("clickwrap.event_types.#{event.event_type}", default: event.event_type.humanize) %>
+          </span>
+        </li>
+      <% end %>
+    </ul>
+  <% else %>
+    <p class="clickwrap-empty"><%= t("clickwrap.receipts.empty") %></p>
+  <% end %>
+</div>

data/app/views/clickwrap/receipts/show.html.erb

@@ -0,0 +1,91 @@
+<%#
+  One receipt, in human-readable form. The canonical JSON is one link away and
+  is the verifiable artifact; this page is the projection of it a person can
+  read.
+
+  The closing note is part of the product, not a disclaimer bolted on: it says
+  exactly what this record does and does not show, in plain words, on the same
+  page as the record itself.
+%>
+<%= clickwrap_styles %>
+
+<div class="clickwrap clickwrap-screen">
+  <header class="clickwrap-screen__header">
+    <h1 class="clickwrap-screen__title"><%= t("clickwrap.receipts.show_title") %></h1>
+    <p class="clickwrap-screen__intro">
+      <%= t("clickwrap.receipts.event_id") %>: <code class="clickwrap-code"><%= @event.id %></code>
+    </p>
+  </header>
+
+  <dl class="clickwrap-facts">
+    <dt><%= t("clickwrap.receipts.policy") %></dt>
+    <dd><%= @event.policy_key %></dd>
+
+    <dt><%= t("clickwrap.receipts.event_type") %></dt>
+    <dd><%= t("clickwrap.event_types.#{@event.event_type}", default: @event.event_type.humanize) %></dd>
+
+    <dt><%= t("clickwrap.receipts.recorded_at_by_server") %></dt>
+    <dd><%= @event.recorded_at_by_server&.utc&.strftime("%Y-%m-%d %H:%M:%S UTC") %></dd>
+
+    <% if @event.presentation_manifest.present? %>
+      <dt><%= t("clickwrap.receipts.submit_button_text") %></dt>
+      <dd><%= @event.presentation_manifest["submit_button_text"] %></dd>
+
+      <%# When the offer was one control carrying one composed sentence, the
+          acts below say what was recorded and this says what was read. %>
+      <% if (sentence = @event.presentation_manifest.dig("combined_control", "sentence")) %>
+        <dt><%= t("clickwrap.receipts.combined_sentence") %></dt>
+        <dd><%= sentence %></dd>
+      <% end %>
+    <% end %>
+  </dl>
+
+  <h2 class="clickwrap-screen__subtitle"><%= t("clickwrap.receipts.acts") %></h2>
+  <ul class="clickwrap-acts">
+    <% @event.statements.each do |statement| %>
+      <li class="clickwrap-acts__item">
+        <p class="clickwrap-acts__assertion"><%= statement.assertion_text %></p>
+        <p class="clickwrap-acts__meta">
+          <%= t("clickwrap.kinds.#{statement.kind}", default: statement.kind.humanize) %>
+          —
+          <%= t("clickwrap.actions.#{statement.action}", default: statement.action.to_s.humanize) %>
+          <% if statement.offered_and_not_taken? %>
+            — <%= t("clickwrap.receipts.offered_and_not_taken") %>
+          <% end %>
+        </p>
+      </li>
+    <% end %>
+  </ul>
+
+  <% if @event.documents.any? %>
+    <h2 class="clickwrap-screen__subtitle"><%= t("clickwrap.receipts.documents") %></h2>
+    <ul class="clickwrap-documents">
+      <% @event.documents.each do |document| %>
+        <li class="clickwrap-documents__item">
+          <% if document.document_version_id.present? %>
+            <%= link_to document.document_key,
+                  clickwrap_document_version_path(document.document_version_id),
+                  class: "clickwrap-documents__link",
+                  target: "_blank",
+                  rel: "noopener" %>
+          <% else %>
+            <span class="clickwrap-documents__link"><%= document.document_key %></span>
+          <% end %>
+          <span class="clickwrap-documents__version">
+            <%= t("clickwrap.ui.document_version", version: document.version_label) %>
+            (<%= document.locale %>)
+          </span>
+          <code class="clickwrap-code clickwrap-code--digest"><%= document.source_content_digest %></code>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+
+  <p class="clickwrap-screen__actions">
+    <%= link_to t("clickwrap.receipts.canonical_json"),
+          clickwrap_receipt_path(@event.id, format: :json),
+          class: "clickwrap-link" %>
+  </p>
+
+  <p class="clickwrap-note"><%= t("clickwrap.receipts.what_this_records") %></p>
+</div>

data/app/views/clickwrap/shared/_error_summary.html.erb

@@ -0,0 +1,39 @@
+<%#
+  The error summary, at the top of the block where a person looking for what
+  went wrong will find it.
+
+  role="alert" so assistive technology announces it when the failed submission
+  re-renders. tabindex="-1" so it can hold focus, and `autofocus` so the browser
+  moves focus here on load without a line of JavaScript — this whole file has to
+  work when the page never runs a script.
+
+  Each entry links to the control it is about, so the fix is one press away
+  rather than a scroll and a hunt. One control gets one entry, whether it answers
+  one statement or a whole composed sentence: several lines pointing at the same
+  checkbox would be a list of the page's internals rather than of a person's
+  problems. The message is TEXT: the styling underlines it, but nothing here
+  depends on a color being seen.
+
+  Locals: presentation, entries — [{ control_id:, message: }]
+%>
+<% if entries.any? %>
+  <div class="clickwrap-error-summary"
+       id="<%= "clickwrap_#{presentation.policy_key}_errors" %>"
+       role="alert"
+       tabindex="-1"
+       autofocus>
+    <h2 class="clickwrap-error-summary__heading">
+      <%= t("clickwrap.ui.error_summary_heading") %>
+    </h2>
+
+    <ul class="clickwrap-error-summary__list">
+      <% entries.each do |entry| %>
+        <li class="clickwrap-error-summary__item">
+          <a class="clickwrap-error-summary__link" href="#<%= entry[:control_id] %>">
+            <%= entry[:message] %>
+          </a>
+        </li>
+      <% end %>
+    </ul>
+  </div>
+<% end %>

data/app/views/clickwrap/shared/_fields.html.erb

@@ -0,0 +1,100 @@
+<%#
+  The reference presentation partial.
+
+  Everything that renders a policy goes through this file: `form.clickwrap`,
+  `form.clickwrap_fields`, and the engine's own standalone capture screen. It is
+  plain ERB with no framework, no JavaScript, and no dependency beyond Rails'
+  own tag helpers, because it has to work unchanged inside a Tailwind app, a
+  Bootstrap app, a ViewComponent app, and an app with a hand-written stylesheet.
+
+  Eject it and it is yours:
+
+    bin/rails generate clickwrap:views
+
+  Your copy at app/views/clickwrap/shared/_fields.html.erb shadows this one
+  automatically — the helper renders the partial by NAME, never by path.
+
+  The default shape is ONE line:
+
+    [ ] I agree to the Terms of Service and I acknowledge the Privacy Policy.
+
+  The presenter decides whether a policy can be offered that way and signs the
+  exact sentence into the manifest when it can. Everything that line could not
+  honestly absorb — an optional consent, a recorded yes/no, copy the application
+  wrote itself — follows it as a control of its own, and a policy with nothing
+  composable is entirely that. Both go through the same statement partial, which
+  is why `itemized_statements` is the list to walk and `statements` is not:
+  rendering a second control for a statement the line already answers offers a
+  choice nobody has.
+
+  What this partial deliberately does NOT contain is a hidden field carrying a
+  server-owned decision. No IP address, no browser user-agent, no geolocation,
+  no policy version, no document digest, no validity window, no retention rule.
+  The only hidden field here is the signed presentation token, which is the
+  server's own statement about what it offered — the browser answers the offer,
+  it never writes it.
+
+  Locals:
+    presentation    — a Clickwrap::Presenter::Result
+    submit          — { text:, options: } to render the action here, or nil
+    after           — markup the host rendered from the presentation itself
+                      (the `form.clickwrap_fields do |clickwrap|` block), or nil
+    errors          — { "statement_key" => "message" } from a failed capture
+    wrapper_options — HTML options for the wrapper element
+%>
+<%
+  errors = (local_assigns[:errors] || {}).to_h { |key, value| [key.to_s, value] }
+  submit = local_assigns[:submit]
+  after = local_assigns[:after]
+  wrapper_options = (local_assigns[:wrapper_options] || {}).symbolize_keys
+  wrapper_classes = ["clickwrap", "clickwrap-fields", wrapper_options.delete(:class)].compact
+
+  combined = presentation.combined
+  # One control shows one message, whether it answers one statement or three.
+  combined_error = combined && errors.values_at(*combined.statement_keys).compact.first
+  controls = [combined, *presentation.itemized_statements].compact
+
+  error_entries = controls.filter_map do |control|
+    message = control.equal?(combined) ? combined_error : errors[control.key]
+    next if message.blank?
+
+    { control_id: control.control_id, message: Array(message).join(" ") }
+  end
+%>
+<%= tag.div(**wrapper_options, class: wrapper_classes) do %>
+  <%= render "clickwrap/shared/error_summary",
+        presentation: presentation,
+        entries: error_entries %>
+
+  <%# The server's statement of what it offered, signed and short-lived. %>
+  <%= hidden_field_tag "clickwrap_submission[presentation_token]", presentation.token, id: nil %>
+
+  <div class="clickwrap-statements">
+    <% controls.each do |control| %>
+      <%= render "clickwrap/shared/statement",
+            statement: control,
+            error: control.equal?(combined) ? combined_error : errors[control.key] %>
+    <% end %>
+  </div>
+
+  <%# The action, rendered from the same presentation as the controls above it,
+      so the words recorded in the manifest are the words on the button. Document
+      links are above this point, always: a link that only appears after the call
+      to action has already been pressed is not a link to anything. %>
+  <% if submit %>
+    <div class="clickwrap-actions">
+      <%
+        button_options = (submit[:options] || {}).symbolize_keys
+        button_classes = ["clickwrap-submit", button_options.delete(:class)].compact
+      %>
+      <%= submit_tag submit[:text], **button_options, class: button_classes %>
+    </div>
+  <% end %>
+
+  <%# The host's own action, rendered by its own markup from this same
+      presentation. It sits here, after the controls and after the document
+      links, for exactly the reason above. %>
+  <% if after.present? %>
+    <div class="clickwrap-actions"><%= after %></div>
+  <% end %>
+<% end %>