clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/document_renderer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "erb"
+# Require the sanitizer implementation without loading the Action View helper
+# facade. Requiring `rails-html-sanitizer` while Action View is booting can
+# create a circular require; these are the library's implementation entrypoints
+# and do not install unrelated helper methods.
+require "loofah"
+require "rails/html/scrubbers"
+require "rails/html/sanitizer"
+
+module Clickwrap
+  # Safe, dependency-free rendering for the text formats most legal documents
+  # use. It intentionally favors faithful, readable text over clever Markdown
+  # interpretation: source characters are escaped, then placed in a <pre>
+  # element. Applications that want richer Markdown may supply a renderer, but
+  # its HTML still passes through #sanitize_html before Clickwrap stores it.
+  class DocumentRenderer
+    NAME = "clickwrap_safe_document_renderer"
+    VERSION = "1"
+    SANITIZER_NAME = "rails_safe_list_sanitizer"
+    SANITIZER_VERSION = "1"
+
+    SAFE_TAGS = %w[
+      a abbr b blockquote br cite code dd del details div dl dt em h1 h2 h3 h4 h5 h6
+      hr i ins kbd li mark ol p pre q s samp small span strong sub summary sup table
+      tbody td tfoot th thead tr u ul var
+    ].freeze
+    SAFE_ATTRIBUTES = %w[href title lang dir class id colspan rowspan scope].freeze
+
+    def call(bytes, definition)
+      text = utf8_text!(bytes, definition)
+
+      html = case definition.media_type
+             when "text/html" then text
+             when "text/markdown", "text/plain", "application/json"
+               %(<pre class="clickwrap-document-source">#{ERB::Util.html_escape(text)}</pre>)
+             else
+               return nil
+             end
+
+      {
+        bytes: self.class.sanitize_html(html),
+        media_type: "text/html; charset=utf-8",
+        renderer_name: NAME,
+        renderer_version: VERSION,
+        sanitizer_name: SANITIZER_NAME,
+        sanitizer_version: SANITIZER_VERSION
+      }
+    end
+
+    def self.sanitize_html(html)
+      safe_list_sanitizer_class.new.sanitize(
+        html.to_s,
+        tags: SAFE_TAGS,
+        attributes: SAFE_ATTRIBUTES
+      ).to_s
+    end
+
+    def self.safe_list_sanitizer_class
+      return Rails::HTML5::SafeListSanitizer if defined?(Rails::HTML5::SafeListSanitizer)
+      return Rails::HTML4::SafeListSanitizer if defined?(Rails::HTML4::SafeListSanitizer)
+
+      raise ConfigurationError,
+            "Clickwrap could not find Rails::HTML5::SafeListSanitizer or " \
+            "Rails::HTML4::SafeListSanitizer. Install a rails-html-sanitizer version that " \
+            "provides one of those supported safe-list sanitizers."
+    end
+    private_class_method :safe_list_sanitizer_class
+
+    private
+
+    def utf8_text!(bytes, definition)
+      text = bytes.to_s.dup.force_encoding(Encoding::UTF_8)
+      return text if text.valid_encoding?
+
+      raise DefinitionError,
+            "Document #{definition} cannot be rendered as text because its bytes are not valid UTF-8. " \
+            "Store binary source with :active_storage (or a byte-preserving resolver) and provide " \
+            "a reviewed renderer for the representation people should be offered."
+    end
+  end
+end

data/lib/clickwrap/document_renderers/markdown.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  module DocumentRenderers
+    # Optional Markdown rendering for the representation people are offered.
+    #
+    # The reference renderer deliberately escapes Markdown into a <pre> block:
+    # faithful, dependency-free, and ugly for a forty-page Terms document. This
+    # renderer produces real HTML instead, using whichever Markdown library the
+    # application already bundles — it is opt-in and it adds no dependency:
+    #
+    #   Clickwrap.configure do |config|
+    #     config.document_renderer = :markdown
+    #   end
+    #
+    # Three engines are recognized, in order: Commonmarker (1.x and the older
+    # CommonMarker 0.x), Redcarpet, and Kramdown. An application whose Markdown
+    # dialect needs specific options can inject its own rendering instead and
+    # must name it, because the receipt records which renderer produced the
+    # offered bytes:
+    #
+    #   config.document_renderer = Clickwrap::DocumentRenderers::Markdown.new(
+    #     render_markdown_with: ->(markdown_text) { MyMarkdown.render(markdown_text) },
+    #     engine_name: "my_markdown",
+    #     engine_version: MyMarkdown::VERSION
+    #   )
+    #
+    # A leading YAML front-matter block (the Jekyll/Sitepress convention) is
+    # stripped from the RENDERED representation only — the source digest still
+    # covers the exact file bytes, front matter included. Bundled engines'
+    # output always passes through the same safe-list sanitizer as the
+    # reference renderer, so a Markdown library's raw-HTML passthrough cannot
+    # smuggle markup into an offer. A host-supplied `render_markdown_with:`
+    # may additionally pass `sanitize_rendered_html: false` when its own pages
+    # serve the renderer's output verbatim: re-sanitizing reparses the HTML
+    # and changes its bytes, and a stored digest must describe exactly what
+    # readers were shown. The provenance records which choice was made.
+    # Non-Markdown documents delegate to the reference renderer unchanged.
+    class Markdown
+      NAME = "clickwrap_markdown_document_renderer"
+      VERSION = "1"
+
+      def initialize(render_markdown_with: nil, engine_name: nil, engine_version: nil,
+                     sanitize_rendered_html: true)
+        @sanitize_rendered_html = sanitize_rendered_html != false
+
+        if !@sanitize_rendered_html && render_markdown_with.nil?
+          raise ConfigurationError,
+                "sanitize_rendered_html: false is only available with your own " \
+                "render_markdown_with. Clickwrap's bundled engines always sanitize; skipping " \
+                "sanitization is a promise about a rendering pipeline YOU own — that its " \
+                "output is exactly what your own pages already serve to readers."
+        end
+
+        if render_markdown_with
+          unless render_markdown_with.respond_to?(:call)
+            raise ConfigurationError,
+                  "render_markdown_with must respond to call(markdown_text) and return HTML."
+          end
+          if engine_name.to_s.strip.empty?
+            raise ConfigurationError,
+                  "A custom render_markdown_with needs an engine_name (and ideally an " \
+                  "engine_version), because receipts record which renderer produced the " \
+                  "bytes a person was offered."
+          end
+
+          @render_markdown = render_markdown_with
+          @engine_name = engine_name.to_s
+          @engine_version = engine_version.to_s.strip.empty? ? "unstated" : engine_version.to_s
+        else
+          @render_markdown, @engine_name, @engine_version = resolve_bundled_engine
+        end
+
+        @fallback = DocumentRenderer.new
+      end
+
+      attr_reader :engine_name, :engine_version
+
+      def call(bytes, definition)
+        return @fallback.call(bytes, definition) unless definition.media_type == "text/markdown"
+
+        text = utf8_text!(bytes, definition)
+        html = @render_markdown.call(FrontMatter.strip(text))
+
+        if @sanitize_rendered_html
+          {
+            bytes: DocumentRenderer.sanitize_html(html),
+            media_type: "text/html; charset=utf-8",
+            renderer_name: NAME,
+            renderer_version: "#{VERSION} (#{@engine_name} #{@engine_version})",
+            sanitizer_name: DocumentRenderer::SANITIZER_NAME,
+            sanitizer_version: DocumentRenderer::SANITIZER_VERSION
+          }
+        else
+          # Byte parity with the host's own pages is the point: re-sanitizing
+          # reparses and re-serializes the HTML, so the stored digest would
+          # describe bytes nobody was ever shown. The provenance says plainly
+          # that no sanitizer ran — the host's rendering pipeline owns safety.
+          {
+            bytes: html.to_s.dup.force_encoding(Encoding::UTF_8),
+            media_type: "text/html; charset=utf-8",
+            renderer_name: NAME,
+            renderer_version: "#{VERSION} (#{@engine_name} #{@engine_version})",
+            sanitizer_name: "none",
+            sanitizer_version: "host_renderer_output_stored_verbatim"
+          }
+        end
+      end
+
+      private
+
+      def resolve_bundled_engine
+        commonmarker_engine || redcarpet_engine || kramdown_engine ||
+          raise(ConfigurationError,
+                "config.document_renderer = :markdown needs a Markdown library, and none of " \
+                "the ones Clickwrap recognizes (commonmarker, redcarpet, kramdown) is " \
+                "available in this application. Add one of them to your Gemfile, or supply " \
+                "your own rendering with " \
+                "Clickwrap::DocumentRenderers::Markdown.new(render_markdown_with:, engine_name:).")
+      end
+
+      def commonmarker_engine
+        attempt_require("commonmarker")
+
+        if defined?(::Commonmarker)
+          [->(text) { ::Commonmarker.to_html(text) }, "commonmarker", loaded_gem_version("commonmarker")]
+        elsif defined?(::CommonMarker)
+          [->(text) { ::CommonMarker.render_html(text) }, "commonmarker", loaded_gem_version("commonmarker")]
+        end
+      end
+
+      def redcarpet_engine
+        attempt_require("redcarpet")
+        return unless defined?(::Redcarpet::Markdown)
+
+        # A fresh renderer per call: Redcarpet's renderer objects carry state
+        # between renders and are not safe to share across threads.
+        render = lambda do |text|
+          ::Redcarpet::Markdown.new(
+            ::Redcarpet::Render::HTML.new(with_toc_data: true),
+            tables: true, autolink: true, fenced_code_blocks: true, strikethrough: true,
+            footnotes: true, no_intra_emphasis: true
+          ).render(text)
+        end
+        [render, "redcarpet", loaded_gem_version("redcarpet")]
+      end
+
+      def kramdown_engine
+        attempt_require("kramdown")
+        return unless defined?(::Kramdown::Document)
+
+        [->(text) { ::Kramdown::Document.new(text).to_html }, "kramdown", loaded_gem_version("kramdown")]
+      end
+
+      def attempt_require(name)
+        require name
+      rescue LoadError
+        nil
+      end
+
+      def loaded_gem_version(name)
+        Gem.loaded_specs[name]&.version&.to_s || "unstated"
+      end
+
+      def utf8_text!(bytes, definition)
+        text = bytes.to_s.dup.force_encoding(Encoding::UTF_8)
+        return text if text.valid_encoding?
+
+        raise DefinitionError,
+              "Document #{definition} cannot be rendered as Markdown because its bytes are " \
+              "not valid UTF-8."
+      end
+    end
+  end
+end

data/lib/clickwrap/document_renderers/markdown_rails.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  module DocumentRenderers
+    # Byte parity with the application's own pages, by construction.
+    #
+    # Content-file Rails apps (Sitepress and friends) render their public
+    # legal pages through the `markdown-rails` gem, whose initializer
+    # registers a renderer for `.md` templates:
+    #
+    #   MarkdownRails.handle :md do
+    #     ApplicationMarkdown.new
+    #   end
+    #
+    # When the same files are also Clickwrap documents, what people accept and
+    # what the public page serves must be the SAME BYTES — same renderer, same
+    # options, no re-sanitization pass changing entities behind the digest.
+    # Wiring that by hand means a lambda, an engine name, gem versions, and a
+    # parity test, all copied between applications. This renderer says it once:
+    #
+    #   Clickwrap.configure do |config|
+    #     config.document_renderer = :markdown_rails
+    #   end
+    #
+    # At render time it asks markdown-rails for the exact renderer object the
+    # application's own `.md` pages go through, renders through it, stores the
+    # output verbatim (`sanitizer_name: "none"` in the provenance — safety
+    # stays where it already lives, in the pipeline every public page trusts),
+    # and records honest provenance: the renderer class the application
+    # registered, plus the markdown-rails and Markdown-engine gem versions.
+    #
+    # The handler is resolved LAZILY, at first render, never at configuration
+    # time: Rails initializers run alphabetically, so `clickwrap.rb` usually
+    # runs before `markdown.rb`, and an eager lookup would capture the stock
+    # default renderer instead of the application's own.
+    #
+    # Honest bound: the renderer is called directly, without a view context —
+    # exactly how a frozen document must render, because a snapshot cannot
+    # depend on the request it happened to be published during. Markdown that
+    # calls Rails view helpers (image_tag and friends) fails loudly at publish;
+    # documents like that need the explicit lambda form of
+    # Clickwrap::DocumentRenderers::Markdown instead.
+    class MarkdownRails
+      HANDLER_EXTENSION = :md
+
+      def initialize
+        # The gem must be bundled for this choice to ever work, and a missing
+        # bundle is a configuration mistake worth failing the boot for. The
+        # HANDLER may legitimately not be registered yet — see the class
+        # comment — so that half of the check waits until render time.
+        #
+        # The handler file loads first on purpose: markdown-rails' engine runs
+        # an on_load(:action_view) hook that references its own Handler
+        # constant, and when Action View is already loaded (it is, here) that
+        # hook fires mid-require, before the entry file has declared the
+        # autoload the hook depends on.
+        begin
+          require "markdown-rails/handler"
+          require "markdown-rails"
+        rescue LoadError
+          raise ConfigurationError,
+                "config.document_renderer = :markdown_rails needs the markdown-rails gem, and " \
+                "it is not in this application's bundle. Add `gem \"markdown-rails\"` (the " \
+                "Sitepress content stack), or render through your own pipeline with " \
+                "Clickwrap::DocumentRenderers::Markdown.new(render_markdown_with:, engine_name:)."
+        end
+
+        @fallback = DocumentRenderer.new
+      end
+
+      def call(bytes, definition)
+        return @fallback.call(bytes, definition) unless definition.media_type == "text/markdown"
+
+        application_markdown_renderer_for(definition).call(bytes, definition)
+      end
+
+      # The provenance the application's registered renderer would produce
+      # right now — exposed so hosts and tests can ask "which renderer will my
+      # documents publish through?" in one call.
+      def engine_name
+        "markdown_rails/#{registered_renderer_class_name}"
+      end
+
+      def engine_version
+        %w[markdown-rails redcarpet commonmarker kramdown].filter_map do |gem_name|
+          spec = Gem.loaded_specs[gem_name]
+          "#{gem_name} #{spec.version}" if spec
+        end.join(" / ").presence || "unstated"
+      end
+
+      private
+
+      # A fresh delegate per call, resolved from the registry markdown-rails
+      # keeps: publish-time work, and late binding keeps development reloads of
+      # the application's renderer class honest.
+      def application_markdown_renderer_for(definition)
+        renderer = registered_renderer(definition)
+
+        Markdown.new(
+          render_markdown_with: ->(markdown_text) { renderer.renderer.render(markdown_text) },
+          engine_name: "markdown_rails/#{renderer.class.name}",
+          engine_version: engine_version,
+          sanitize_rendered_html: false
+        )
+      end
+
+      def registered_renderer(definition = nil)
+        handler = ::MarkdownRails::Handler.handler_for(HANDLER_EXTENSION)
+        if handler.nil?
+          raise ConfigurationError,
+                "config.document_renderer = :markdown_rails found no markdown-rails handler " \
+                "registered for .#{HANDLER_EXTENSION}#{" while rendering document #{definition}" if definition}. " \
+                "Register one in config/initializers/markdown.rb — " \
+                "`MarkdownRails.handle :md { ApplicationMarkdown.new }` — so Clickwrap can " \
+                "render documents through the exact pipeline your own pages use."
+        end
+
+        handler.create_renderer
+      end
+
+      def registered_renderer_class_name
+        registered_renderer.class.name
+      end
+    end
+  end
+end