draftjs_html 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e7da064863d6ce77e04957db9f87f957db61dbbc622bf853c43b7ee6f61b970
-  data.tar.gz: 985ea5ed6ec84cb10a62065858b9fa100ff444a8b0d27f181685ea5f1de609a1
+  metadata.gz: 947546094b93886a5533fe19720c44671066c08ebe079dd9a628cead629e880e
+  data.tar.gz: 280b8abcae0942d236f2352ef8f6aac6fb4a34d51323ed9cb15b8667c8e24d41
 SHA512:
-  metadata.gz: 991ad75b614edd4c5a46290ded23422ed8a7691ef2e1c79328daa5e41d96b43595e8ea025709ced743a3fbe44144efbc6032baad0d09ee165cc1527fa173fb1a
-  data.tar.gz: 15d168a71001ac7fc6dd2505f8fc716c22fb221f5cf25a0b1fc12cc34bd3a9b46c21de5bde8c47d5f4cd643b40c07c219b7b86852cdda7536ce9228c7fc18fb6
+  metadata.gz: c0b41f31e0c06a0c9dd6ee08ad7c4cbfd534875130503439ff21777a3145551fd15ac01496e96ec144a96c69ab4e137b4213eefe5f14c1b0b920bf6759e1d1a9
+  data.tar.gz: 991cabc0dd8a3ccb1785a34f9c629be7b5bc0ee0ec83498ba0e494a234eb3175c5089d3b44a533caa271dd115a499e710cf2bddc5d6442d181ebf2b980438f6c

data/README.md

@@ -59,8 +59,8 @@ raw_draftjs = {
 
 DraftjsHtml.to_html(raw_draftjs, options: {
   entity_style_mappings:  {
-    abc: ->(entity, content) {
-      %Q{<a href="https://example.com/?id=#{entity.data['user_id']}">#{content}</a>}
+    abc: ->(entity, content, *) {
+      DraftjsHtml::Node.new('a', { href: "https://example.com/?id=#{entity.data['user_id']}" }, content)
     },
   },
 }) # => <p>Hello <a href="https://example.com/?id=123">@Arya</a></p>
@@ -81,8 +81,9 @@ Defaults to `UTF-8`.
 
 Allows the author to specify special mapping functions for entities.
 By default, we render `LINK` and `IMAGE` entities using the standard `<a>` and `<img>` tags, respectively.
-The author may supply a Proc object that returns any object Nokogiri can consume for adding to HTML.
-This includes `String`, `Nokogiri::Document::Fragment`, and `Nokogiri::Document` objects.
+The author may supply a `call`-able object that returns a `DraftjsHtml::Node`-able (or similar).
+If returned a String, it's assumed this content is plaintext (or otherwise unsafe) and its content will be coerced to plaintext.
+See the section on HTML Injection protection for more details.
 
 #### `:block_type_mapping`
 
@@ -128,13 +129,44 @@ However, if you "return" `nil` (or `false-y`) from the proc, it will fallback to
 DraftjsHtml.to_html(raw_draftjs, options: {
   inline_style_renderer: ->(style_names, content) {
     next if style_names != ['CUSTOM']
-    "<pre>#{content}</pre>"
+    Nokogiri::XML::Node.new('pre', document).tap do |node|
+      node.content = content
+    end
   },
 })
 
 # This would use the default inline style rendering UNLESS the *only* applied style for this range was "CUSTOM"
 ```
 
+#### HTML Injection protection
+
+Working with user-generated content can be a dangerous thing.
+While it allows for a lot of flexibility, it also creates some potential attack vectors that you need to be aware of.
+We try to take a "safe by default" stance with this library, and not generate HTML that could be dangerous when we know better.
+
+To facilitate this, we require a little work from you, dear programmer.
+Namely, when specifying special algorithms for generating entities or inline styles, you need to help us keep you safe.
+You can do this by returning a `Nokogiri::XML::Node` or `DraftjsHtml::Node` from any functions you provide that generate HTML.
+This is similar to Ruby on Rails' `#to_html` method, but rather than a monkeypatch, we chose to provide a "marker class" (classes) that we know are safe.
+These classes will handle escaping, encoding, and otherwise "safe generation" for you.
+If you, on the other hand, return a bare `String` from one of the custom render functions, we assume it's _unsafe_ and encode it.
+
+That is, a function like this:
+```ruby
+->(entity, content, document) do
+  "<p>hi!</p>"
+end
+# will become an HTML-entity escaped string (e.g. "&lt;p&gt;hi!&lt;/p&gt;")
+```
+
+Where, a function like this:
+```ruby
+->(entity, content, document) do
+  DraftjsHtml::Node.new('p', {}, 'hi!')
+end
+# will nest HTML nodes as you probably want (e.g. "<p>hi!</p>")
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/draftjs_html/node.rb

@@ -0,0 +1,32 @@
+module DraftjsHtml
+  NokogiriNode = Struct.new(:node) do
+    def to_nokogiri(_document)
+      node
+    end
+  end
+
+  StringNode = Struct.new(:raw) do
+    def to_nokogiri(document)
+      raw
+      Nokogiri::XML::Text.new(raw, document)
+    end
+  end
+
+  Node = Struct.new(:element_name, :attributes, :content) do
+    def self.of(thing)
+      case thing
+      when Nokogiri::XML::Node then NokogiriNode.new(thing)
+      when self.class then thing
+      when String then StringNode.new(thing)
+      else thing
+      end
+    end
+
+    def to_nokogiri(document)
+      Nokogiri::XML::Node.new(element_name, document).tap do |node|
+        node.content = content
+        (attributes || {}).each { |k, v| node[k] = v }
+      end
+    end
+  end
+end

data/lib/draftjs_html/to_html.rb

@@ -1,3 +1,5 @@
+require_relative 'node'
+
 module DraftjsHtml
   class ToHtml
     BLOCK_TYPE_TO_HTML = {
@@ -27,28 +29,25 @@ module DraftjsHtml
       'UNDERLINE' => 'u',
     }.freeze
 
-    DEFAULT_ENTITY_STYLE_FN = ->(_entity, chars) { chars }
+    DEFAULT_ENTITY_STYLE_FN = ->(_entity, chars, _doc) { chars }
     ENTITY_ATTRIBUTE_NAME_MAP = {
       'className' => 'class',
       'url' => 'href',
     }.freeze
     ENTITY_CONVERSION_MAP = {
-      'LINK' => ->(entity, content) {
-        node = Nokogiri::HTML::DocumentFragment.parse('<a>').children.first
-        node.content = content
-        entity.data.slice('url', 'rel', 'target', 'title', 'className').each do |attr, value|
-          node[ENTITY_ATTRIBUTE_NAME_MAP.fetch(attr, attr)] = value
+      'LINK' => ->(entity, content, *) {
+        attributes = entity.data.slice('url', 'rel', 'target', 'title', 'className').each_with_object({}) do |(attr, value), h|
+          h[ENTITY_ATTRIBUTE_NAME_MAP.fetch(attr, attr)] = value
         end
 
-        node
+        DraftjsHtml::Node.new('a', attributes, content)
       },
-      'IMAGE' => ->(entity, _content) {
-        node = Nokogiri::HTML::DocumentFragment.parse('<img>').children.first
-        entity.data.slice('src', 'alt', 'className', 'width', 'height').each do |attr, value|
-          node[ENTITY_ATTRIBUTE_NAME_MAP.fetch(attr, attr)] = value
+      'IMAGE' => ->(entity, *) {
+        attributes = entity.data.slice('src', 'alt', 'className', 'width', 'height').each_with_object({}) do |(attr, value), h|
+          h[ENTITY_ATTRIBUTE_NAME_MAP.fetch(attr, attr)] = value
         end
 
-        node
+        DraftjsHtml::Node.new('img', attributes)
       }
     }.freeze
 
@@ -94,18 +93,22 @@ module DraftjsHtml
       end
     end
 
-    def apply_styles_to(html, style_names, text)
-      return html.parent << text if style_names.empty?
+    def apply_styles_to(html, style_names, child)
+      return append_child(html, child) if style_names.empty?
 
-      custom_render_content = @options[:inline_style_renderer].call(style_names, text)
-      return html.parent << custom_render_content if custom_render_content
+      custom_render_content = @options[:inline_style_renderer].call(style_names, child, @document.parent)
+      return append_child(html, custom_render_content) if custom_render_content
 
       style, *rest = style_names
-      html.public_send(style_element_for(style)) do
-        apply_styles_to(html, rest, text)
+      html.public_send(style_element_for(style)) do |builder|
+        apply_styles_to(builder, rest, child)
       end
     end
 
+    def append_child(nokogiri, child)
+      nokogiri.parent.add_child(DraftjsHtml::Node.of(child).to_nokogiri(@document.parent))
+    end
+
     def block_element_for(block)
       return 'br' if block.blank?
 
@@ -119,7 +122,11 @@ module DraftjsHtml
     def try_apply_entity_to(draftjs, char_range)
       entity = draftjs.find_entity(char_range.entity_key)
       content = char_range.text
-      content = (@options[:entity_style_mappings][entity.type] || DEFAULT_ENTITY_STYLE_FN).call(entity, content) if entity
+      if entity
+        style_fn = (@options[:entity_style_mappings][entity.type] || DEFAULT_ENTITY_STYLE_FN)
+        content = style_fn.call(entity, content, @document.parent)
+      end
+
       content
     end
 

data/lib/draftjs_html/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DraftjsHtml
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: draftjs_html
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - TJ Taylor
@@ -65,6 +65,7 @@ files:
 - lib/draftjs_html/draftjs/entity.rb
 - lib/draftjs_html/draftjs/entity_map.rb
 - lib/draftjs_html/draftjs/to_raw.rb
+- lib/draftjs_html/node.rb
 - lib/draftjs_html/to_html.rb
 - lib/draftjs_html/version.rb
 homepage: https://github.com/dugancathal/draftjs_html