clickwrap 0.0.0 → 0.1.0

data/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+`clickwrap` stores legal-evidence records: frozen document snapshots, signed presentation tokens, append-oriented evidence events with fixed named disposition transitions, canonical receipts, and — only when a policy explicitly asks for them — encrypted IP addresses, browser user-agent strings, and IP-geolocation estimates. Please report suspected vulnerabilities privately, and do not include real evidence records, receipts, presentation tokens, IP addresses, or any other personal data in a report. Redact or synthesize a reproduction instead; a minimal fabricated policy and document reproduce almost every issue just as well.
+
+## Supported versions
+
+Security fixes are released for the latest published version. The maintained test matrix covers Ruby 3.2, 3.3, 3.4, and 4.0 with patched Rails 7.1, 7.2, 8.0, and 8.1 releases. Older Ruby and Rails versions may remain installable for compatibility, but runtimes that no longer receive upstream security fixes are not security-supported.
+
+## Reporting a vulnerability
+
+Use GitHub's **Report a vulnerability** button on the [`clickwrap` security advisories page](https://github.com/rameerez/clickwrap/security/advisories) so the report and any proposed fix remain private. If GitHub's private reporting flow is unavailable, email `rubygems@rameerez.com` with the subject `clickwrap security report`.
+
+Include:
+
+- the affected version and environment;
+- a minimal reproduction or proof of concept, using synthetic documents, policies, and actors;
+- the impact you believe is possible — in particular, whether it affects the capture path (evidence that could be recorded wrongly) or only the verifier/display path (evidence that could be read or rendered wrongly); and
+- any suggested mitigation or patch.
+
+Do not open a public issue for an undisclosed vulnerability. We will acknowledge the report, investigate it, and coordinate disclosure and credit with you. If the issue affects downstream applications, we will prioritize a patched release and clear upgrade guidance, and say plainly whether historical evidence needs review.
+
+## Operational security
+
+`clickwrap` provides evidence mechanics. Applications remain responsible for:
+
+- Rails credentials, the `secret_key_base` that signs presentation tokens, and the `ActiveRecord::Encryption` keys that protect the request-evidence annex — including key rotation and a documented recovery path, since evidence outlives the deployment that wrote it;
+- trusted-proxy configuration (`config.hosts`, `config.action_dispatch.trusted_proxies`) so that `request.remote_ip` reflects the connection the application actually observed rather than a client-supplied header;
+- CSRF protection, session cookie configuration, authentication, and the authorization of every controller action that renders a policy or submits evidence;
+- database, backup, replica, log, and observability access controls, and keeping presentation tokens and request evidence out of application and proxy logs;
+- deciding who may read unredacted request evidence, wiring `config.authorize_receipt_access_with` and `config.authorize_unredacted_request_evidence_access_with` accordingly, and auditing that access; and
+- retention periods, legal holds, and disposition decisions — the gem executes the retention classes you write and refuses to dispose of held evidence, but the periods, the lawful basis for keeping or deleting a record, and the decision to place or release a hold are yours.
+
+The gem does not, and does not claim to, provide compliance with any law, enforceability of any agreement, tamper-proof storage, trusted or attested time, or verified identity. A receipt is evidence of what your application recorded and can be verified against its own canonical bytes; it is not proof that the recorded facts are true, that a person read or understood a document, or that the record could not have been fabricated by someone who controls every source. Independent anchors and provider signatures add only the origin and time evidence they actually supply.

data/app/assets/stylesheets/clickwrap.css

@@ -0,0 +1,241 @@
+/*
+ * clickwrap — bundled default styles.
+ *
+ * Deliberately small and unopinionated. It sets the things that change whether
+ * a person can USE the block — focus you can see, links that look like links,
+ * targets big enough to press, errors that read as errors in words — and stops
+ * well short of a design. Everything is scoped under `.clickwrap`, so dropping
+ * this file into a host stylesheet cannot repaint anything else on the page.
+ *
+ * Self-contained on purpose: engine views can't lean on the host's CSS
+ * framework (a Tailwind host never scans gem view files, so utility classes
+ * used here would simply not exist in its build). Semantic clickwrap-* classes
+ * plus plain modern CSS work in any host with zero build integration.
+ *
+ * Theme it with CSS variables from any host stylesheet:
+ *
+ *   :root {
+ *     --clickwrap-link: #1d4ed8;
+ *     --clickwrap-error: #b3261e;
+ *   }
+ *
+ * Want something completely different? `bin/rails generate clickwrap:views`
+ * ejects the templates into your app; restyle them and skip this file.
+ *
+ * What this file cannot do is make a page accessible. Placement, contrast
+ * against YOUR background, surrounding clutter, reading order, and the words
+ * themselves belong to the host page. These are defaults that try not to be the
+ * problem.
+ */
+
+.clickwrap {
+  --clickwrap-text: #111827;
+  --clickwrap-muted: #4b5563;
+  --clickwrap-link: #1d4ed8;
+  --clickwrap-link-visited: #6b21a8;
+  --clickwrap-error: #b3261e;
+  --clickwrap-error-surface: #fdf2f2;
+  --clickwrap-border: #6b7280;
+  --clickwrap-focus: #111827;
+  --clickwrap-radius: 0.375rem;
+
+  color: var(--clickwrap-text);
+  font: inherit;
+  line-height: 1.5;
+}
+
+/* --- Focus ------------------------------------------------------------------
+ * A visible focus ring on everything focusable, in both directions: the outline
+ * is drawn, and it is offset so it stays visible on top of a control that has
+ * its own border. Never `outline: none`.
+ */
+
+.clickwrap :is(a, button, input, summary, [tabindex]):focus-visible {
+  outline: 3px solid var(--clickwrap-focus);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+
+/* --- Screen-reader-only text -------------------------------------------------
+ * The "(opens in a new tab)" truth without the clutter: announced, never drawn.
+ * Not `display: none` and not `visibility: hidden` — both remove it from the
+ * accessibility tree, which is the one place it needs to exist.
+ */
+
+.clickwrap-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* --- Statements --------------------------------------------------------------
+ * The default is one line: a checkbox and a sentence with links in it. Aligned
+ * on the first line's baseline rather than the box's top edge, so the control
+ * sits with the words instead of above them, and nothing wraps to a second row
+ * that a person has to read as a second thing.
+ */
+
+.clickwrap-statements { display: flex; flex-direction: column; gap: 1rem; }
+
+.clickwrap-statement__control { display: flex; align-items: flex-start; gap: 0.6rem; }
+
+.clickwrap-statement__checkbox,
+.clickwrap-statement__radio {
+  /* Sized in em so the box matches the sentence it belongs to instead of
+     towering over small text, and optically centered against the FIRST line
+     of the label: (line-height minus box) halved. Flex `baseline` cannot do
+     this — a checkbox aligns its bottom edge to the baseline and ends up
+     floating high. The rem fallback covers engines without the lh unit. */
+  width: 1em;
+  height: 1em;
+  margin: 0.2em 0 0;
+  margin-top: calc((1lh - 1em) / 2);
+  flex: 0 0 auto;
+  accent-color: var(--clickwrap-focus);
+}
+
+.clickwrap-statement__label,
+.clickwrap-statement__choice-label { cursor: pointer; }
+
+.clickwrap-statement__choices {
+  border: 1px solid var(--clickwrap-border);
+  border-radius: var(--clickwrap-radius);
+  padding: 0.75rem 1rem;
+  margin: 0;
+}
+
+.clickwrap-statement__legend { font-weight: 600; padding: 0 0.25rem; }
+.clickwrap-statement__choice { display: inline-flex; align-items: center; gap: 0.4rem; margin-right: 1rem; }
+
+/* --- Documents ---------------------------------------------------------------
+ * Links look like links: underlined, in a conventional link color, and distinct
+ * from the surrounding text by more than color alone. In the composed line they
+ * sit inside the sentence; on an itemized statement they sit under it.
+ */
+
+.clickwrap-documents { list-style: none; margin: 0.4rem 0 0; padding: 0 0 0 1.75rem; }
+.clickwrap-documents__item { margin: 0.15rem 0; font-size: 0.9375rem; }
+
+.clickwrap-documents__link,
+.clickwrap-link {
+  /* The links read AS PART of the sentence: same color as the words around
+     them, distinguished by a subtle underline — still a non-color signal, so
+     the distinction survives color-blindness and forced-colors modes. The
+     underline firms up on hover/focus as the affordance. */
+  color: inherit;
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-decoration-color: color-mix(in srgb, currentColor 45%, transparent);
+  text-underline-offset: 0.18em;
+}
+
+.clickwrap-documents__link:hover,
+.clickwrap-documents__link:focus-visible,
+.clickwrap-link:hover,
+.clickwrap-link:focus-visible { text-decoration-color: currentColor; }
+
+.clickwrap-documents__link:visited,
+.clickwrap-link:visited { color: inherit; }
+
+/* Versions belong on a receipt, where somebody is reading the record. Beside a
+   checkbox they are noise nobody can act on. */
+.clickwrap-documents__version { color: var(--clickwrap-muted); font-size: 0.8125rem; }
+
+/* --- Errors ------------------------------------------------------------------
+ * Never color alone. The message is words, it is prefixed by the word "Error",
+ * and the block carries a heavy left rule — so it still reads as an error in
+ * grayscale, in high-contrast mode, and to someone who cannot see red.
+ */
+
+.clickwrap-error-summary {
+  border: 2px solid var(--clickwrap-error);
+  border-left-width: 8px;
+  background: var(--clickwrap-error-surface);
+  border-radius: var(--clickwrap-radius);
+  padding: 0.85rem 1rem;
+  margin: 0 0 1rem;
+}
+
+.clickwrap-error-summary__heading { margin: 0 0 0.5rem; font-size: 1.0625rem; font-weight: 700; }
+.clickwrap-error-summary__list { margin: 0; padding-left: 1.25rem; }
+.clickwrap-error-summary__link { color: var(--clickwrap-error); text-decoration: underline; }
+
+.clickwrap-statement--invalid {
+  border-left: 4px solid var(--clickwrap-error);
+  padding-left: 0.75rem;
+}
+
+.clickwrap-statement__error { color: var(--clickwrap-error); margin: 0.35rem 0 0; font-size: 0.9375rem; }
+.clickwrap-statement__error-prefix { font-weight: 700; }
+
+.clickwrap-flash { padding: 0.75rem 1rem; border-radius: var(--clickwrap-radius); }
+.clickwrap-flash--alert {
+  border: 2px solid var(--clickwrap-error);
+  border-left-width: 8px;
+  background: var(--clickwrap-error-surface);
+}
+
+/* --- Actions ------------------------------------------------------------------ */
+
+.clickwrap-actions { margin-top: 1.25rem; }
+
+.clickwrap-submit {
+  font: inherit;
+  padding: 0.6rem 1.1rem;
+  border-radius: var(--clickwrap-radius);
+  border: 1px solid var(--clickwrap-focus);
+  background: var(--clickwrap-focus);
+  color: #ffffff;
+  cursor: pointer;
+  min-height: 2.75rem;
+}
+
+/* --- Engine screens ------------------------------------------------------------
+ * Only the four pages this gem ships. A host page that embeds the form helper
+ * keeps its own layout entirely.
+ */
+
+.clickwrap-screen { max-width: 42rem; margin: 0 auto; padding: 1.5rem 1.25rem 3rem; }
+.clickwrap-screen__title { font-size: 1.5rem; margin: 0 0 0.35rem; }
+.clickwrap-screen__subtitle { font-size: 1.125rem; margin: 1.5rem 0 0.5rem; }
+.clickwrap-screen__intro { color: var(--clickwrap-muted); margin: 0 0 1.25rem; }
+.clickwrap-screen__actions { margin-top: 1.5rem; }
+
+.clickwrap-facts { display: grid; grid-template-columns: minmax(10rem, auto) 1fr; gap: 0.35rem 1rem; margin: 0; }
+.clickwrap-facts dt { color: var(--clickwrap-muted); }
+.clickwrap-facts dd { margin: 0; }
+
+.clickwrap-receipts, .clickwrap-acts { list-style: none; margin: 0; padding: 0; }
+
+.clickwrap-receipts__item,
+.clickwrap-acts__item {
+  padding: 0.75rem 0;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.12);
+}
+
+.clickwrap-receipts__link { color: var(--clickwrap-link); text-decoration: underline; font-weight: 600; }
+.clickwrap-receipts__meta, .clickwrap-acts__meta { display: block; color: var(--clickwrap-muted); font-size: 0.875rem; }
+.clickwrap-acts__assertion { margin: 0; }
+
+.clickwrap-code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.8125rem;
+  word-break: break-all;
+}
+
+.clickwrap-code--digest { display: block; color: var(--clickwrap-muted); }
+.clickwrap-empty, .clickwrap-note { color: var(--clickwrap-muted); }
+.clickwrap-note { margin-top: 2rem; font-size: 0.875rem; }
+
+/* Respect a reader's own contrast and motion settings rather than overriding
+   them: in forced-colors mode the system palette wins outright. */
+@media (forced-colors: active) {
+  .clickwrap :is(a, button, input, [tabindex]):focus-visible { outline: 3px solid CanvasText; }
+  .clickwrap-error-summary, .clickwrap-flash--alert { border-color: CanvasText; }
+}

data/app/controllers/clickwrap/application_controller.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # Base controller for every engine screen. It inherits from the HOST's
+  # controller (`config.parent_controller_class_name`, "::ApplicationController"
+  # by default) so the host's layout, helpers, authentication filters, locale
+  # switching, and exception handling all apply to these screens for free — the
+  # same integration style as the sessions, chats, and api_keys gems.
+  #
+  # NOTE: the superclass is resolved when this class is AUTOLOADED, which in a
+  # booted app happens after initializers have run — so a
+  # `config.parent_controller_class_name` set in
+  # config/initializers/clickwrap.rb is honored. In development the class
+  # reloads on change and picks up configuration changes with it.
+  class ApplicationController < Clickwrap.config.parent_controller_class_name.constantize
+    # The view-layer DSL (`helper`, `helper_method`, `layout`) does not exist on
+    # ActionController::API, and an API-only host that bundles this gem for its
+    # model and service APIs still eager-loads this class in production, mounted
+    # or not. Guarding keeps such a host bootable; the HTML screens themselves
+    # still need a Base-derived parent controller, which is the default.
+    helper Clickwrap::EngineHelper if respond_to?(:helper)
+    helper_method :clickwrap_current_actor, :clickwrap_errors if respond_to?(:helper_method)
+
+    private
+
+    # The host's authentication filters run INSIDE these engine controllers —
+    # that is the entire point of inheriting from the host's parent controller —
+    # and those filters reference the HOST's own route helpers
+    # (`new_session_path` in the Rails authentication generator, custom
+    # redirects in hand-rolled filters), which an isolated engine's route set
+    # cannot resolve. Delegating unknown `*_path`/`*_url` calls to `main_app`
+    # lets the host's code work in here unmodified. It is the standard engine
+    # idiom, and the alternative is asking every host to special-case its own
+    # authentication for these four screens.
+    def method_missing(method, *, &)
+      if method.to_s.end_with?("_path", "_url") && main_app.respond_to?(method)
+        main_app.public_send(method, *, &)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      (method.to_s.end_with?("_path", "_url") && main_app.respond_to?(method)) || super
+    end
+
+    # A destination this application is willing to send someone back to.
+    #
+    # Return-to values arrive from the browser, so they are treated as untrusted
+    # navigation input: a relative path on this host, or nothing. An absolute
+    # URL, a protocol-relative "//evil.example", a scheme, or anything carrying
+    # control characters falls back to the default rather than being repaired
+    # into something that looks close enough.
+    def clickwrap_safe_return_to(candidate, fallback:)
+      value = candidate.to_s.strip
+      return fallback if value.empty?
+      return fallback unless value.start_with?("/")
+      return fallback if value.start_with?("//", "/\\")
+      return fallback if value.match?(/[[:cntrl:]]/)
+
+      uri = begin
+        URI.parse(value)
+      rescue URI::InvalidURIError
+        nil
+      end
+      return fallback if uri.nil? || uri.scheme.present? || uri.host.present?
+
+      value
+    end
+
+    # Actor-owned engine screens authorize only after a real actor exists.
+    # Otherwise a host callback such as `current_user == receipt.actor` could
+    # accidentally authorize the `nil == nil` case for imported or unlinked
+    # evidence.
+    def require_clickwrap_actor
+      head :unauthorized unless clickwrap_current_actor
+    end
+  end
+end

data/app/controllers/clickwrap/captures_controller.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The standalone screen for one policy: the same server-owned presentation the
+  # form-builder helper renders inline, on a page of its own.
+  #
+  # This is what stops a required agreement from becoming a dead end. A gate
+  # redirects here, the person completes the policy in place, and they are
+  # returned to whatever they were trying to do. It is also the screen a host
+  # links to directly for a declaration that has expired or a new Terms version
+  # that needs accepting.
+  class CapturesController < ApplicationController
+    before_action :find_policy
+    before_action :require_clickwrap_actor
+    before_action :load_remediation_context
+    before_action :remember_return_destination
+
+    rescue_from RemediationInvalid, with: :remediation_not_found
+
+    def show
+      @presentation = present_policy
+    end
+
+    def create
+      capture_clickwrap!(@policy.key, subject: @remediation_subject,
+                                      acting_for: @remediation_represented_party,
+                                      **remediation_tenant_option)
+
+      redirect_to @return_to, allow_other_host: false, notice: t("clickwrap.captures.recorded")
+    rescue AnswerInvalid => error
+      re_present_with_error(error.statement_key, t("clickwrap.errors.answer_not_accepted"))
+    rescue SubmissionInvalid, PresentationExpired, PresentationInvalid, ReplayRejected,
+           OneTimeAuthorizationConflict
+      # A stale, replayed, or swapped presentation is not something to repair
+      # quietly: the server offers the policy again and the person answers the
+      # offer they can actually see.
+      re_present_with_error(nil, t("clickwrap.errors.presentation_no_longer_valid"))
+    rescue AuthorityNotVerified
+      # Authority is rechecked at submit. A role removed after the page was
+      # rendered must not become a 500 or a fresh offer that can never succeed.
+      head :forbidden
+    rescue RetryableTransactionError
+      response.set_header("Retry-After", "1")
+      re_present_with_error(nil, t("clickwrap.errors.temporarily_unavailable"), status: :service_unavailable)
+    end
+
+    private
+
+    def find_policy
+      @policy = Clickwrap.policy!(params[:policy_key])
+    rescue UnknownPolicyError
+      head :not_found
+    end
+
+    # Where to go after the policy is satisfied. The gate puts this in the URL
+    # and the form carries it through the POST; both are browser-supplied, so
+    # both go through the same safety check and fall back to this engine's own
+    # root rather than to anywhere interesting.
+    def remember_return_destination
+      candidate = @remediation_context&.return_to || params[:return_to]
+      @return_to = clickwrap_safe_return_to(candidate, fallback: clickwrap_engine_routes.root_path)
+    end
+
+    def load_remediation_context
+      token = params[:remediation_token].presence
+
+      if token.nil?
+        if @policy.subject_bound?
+          raise RemediationInvalid,
+                "This subject-bound policy needs a signed remediation route from the blocked action."
+        end
+
+        # A policy that permits acting for a represented party exists to record
+        # WHO was represented. Completing it on the bare engine screen with no
+        # represented party would write permanent evidence whose statements
+        # assert representative authority over nobody — orphan evidence that
+        # reads as more than it is. Those policies arrive here only through a
+        # signed remediation route that carries the represented party.
+        if @policy.authority_rule.present?
+          raise RemediationInvalid,
+                "This policy records representative authority, so it needs a signed remediation " \
+                "route naming the represented party. It cannot be completed standalone."
+        end
+
+        @remediation_token = nil
+        @remediation_subject = nil
+        @remediation_represented_party = nil
+        @remediation_tenant = nil
+        return
+      end
+
+      @remediation_context = resolve_clickwrap_remediation!(@policy.key, token: token)
+      @remediation_token = token
+      @remediation_subject = @remediation_context.subject
+      @remediation_represented_party = @remediation_context.represented_party
+      # The signed token carries the tenant the gate resolved; the engine's own
+      # routes have no ambient tenant, so this is the only truthful source.
+      @remediation_tenant = @remediation_context.tenant_reference.presence
+    end
+
+    def present_policy
+      present_clickwrap(
+        @policy.key,
+        subject: @remediation_subject,
+        acting_for: @remediation_represented_party,
+        locale: I18n.locale,
+        submit_button_text: submit_button_text,
+        **remediation_tenant_option
+      )
+    end
+
+    # Included only when a signed token carried a tenant: a token-less flow
+    # keeps the ordinary policy-aware ambient resolution, while a tokened flow
+    # must use exactly the tenant the issuing gate resolved and signed.
+    def remediation_tenant_option
+      @remediation_tenant.nil? ? {} : { tenant: @remediation_tenant }
+    end
+
+    # The words on the button, recorded in the manifest exactly as rendered. A
+    # host that wants different words translates the key; there is no way for
+    # the rendered button and the recorded text to disagree, because this is the
+    # only place either of them comes from.
+    def submit_button_text
+      t("clickwrap.captures.submit_button_text")
+    end
+
+    def re_present_with_error(statement_key, message, status: 422)
+      if statement_key
+        clickwrap_errors[statement_key.to_s] = message
+      else
+        flash.now[:alert] = message
+      end
+
+      # A new presentation, not the old one: its nonce is spent, and re-offering
+      # a spent token would fail again for a reason that has nothing to do with
+      # what the person got wrong.
+      @presentation = present_policy
+      render :show, status: status
+    end
+
+    def remediation_not_found
+      head :not_found
+    end
+  end
+end

data/app/controllers/clickwrap/document_versions_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The exact rendered bytes of one published document version.
+  #
+  # This is where every document link in every presentation points, and where an
+  # auditor reading a three-year-old receipt ends up. Both get the same response
+  # from the same row, verified against the digest that was recorded when it was
+  # published — `DocumentVersion#content_bytes` refuses to hand back bytes that
+  # no longer match, because silently serving edited content would turn this
+  # action into a way to launder a changed document into an old agreement.
+  #
+  # Retired versions stay reachable on purpose. A version stops being presentable
+  # when it is retired; it never stops being the thing somebody agreed to.
+  class DocumentVersionsController < ApplicationController
+    # Published legal documents are read before anyone is signed in — the signup
+    # form links to them, and that is the moment they matter most. The host's
+    # authentication filter is skipped here and only here. (`raise: false`
+    # because most hosts have neither of these filters; between them they cover
+    # the Rails authentication generator and Devise.)
+    skip_before_action :require_authentication, raise: false
+    skip_before_action :authenticate_user!, raise: false
+
+    def show
+      version = DocumentVersion.find_by(id: params[:id])
+      return head :not_found if version.nil? || !version.published?
+
+      # The linked representation is the exact rendered snapshot bound into the
+      # presentation, not mutable source and never raw unsanitized HTML.
+      response.headers["X-Content-Type-Options"] = "nosniff"
+      response.headers["Content-Security-Policy"] =
+        "default-src 'none'; img-src data:; style-src 'unsafe-inline'; " \
+        "base-uri 'none'; form-action 'none'; frame-ancestors 'self'; sandbox"
+      response.headers["Referrer-Policy"] = "no-referrer"
+      response.headers["Cache-Control"] = "public, max-age=31536000, immutable"
+
+      # A published representation is derived from a specific source artifact.
+      # Refuse to serve either half of a version whose other half has stopped
+      # matching its publication digest; otherwise a corrupt source row could
+      # remain publicly vouched for merely because the rendered snapshot was
+      # untouched.
+      version.content_bytes
+      send_data version.rendered_bytes,
+                type: version.rendered_media_type.presence || version.media_type,
+                filename: download_filename(version, version.rendered_media_type.presence || version.media_type),
+                disposition: "inline"
+    rescue DocumentDigestMismatchError
+      # The stored bytes no longer match their recorded digest. Serving them
+      # anyway would be the one thing this action must never do.
+      head :unprocessable_entity
+    end
+
+    private
+
+    def download_filename(version, media_type)
+      base = [version.document&.document_key, version.version_label, version.locale].compact.join("-")
+
+      "#{base.parameterize}#{extension_for(media_type)}"
+    end
+
+    def extension_for(media_type)
+      case media_type.to_s.split(";", 2).first
+      when "text/markdown" then ".md"
+      when "text/html" then ".html"
+      when "text/plain" then ".txt"
+      when "application/pdf" then ".pdf"
+      else ""
+      end
+    end
+  end
+end